diff options
Diffstat (limited to 'erts/doc')
31 files changed, 8964 insertions, 2157 deletions
diff --git a/erts/doc/src/Makefile b/erts/doc/src/Makefile index b96cbbce40..40f74b78ff 100644 --- a/erts/doc/src/Makefile +++ b/erts/doc/src/Makefile @@ -1,7 +1,7 @@ -# +# # %CopyrightBegin% # -# Copyright Ericsson AB 1997-2016. All Rights Reserved. +# Copyright Ericsson AB 1997-2018. All Rights Reserved. # # Licensed under the Apache License, Version 2.0 (the "License"); # you may not use this file except in compliance with the License. @@ -16,7 +16,7 @@ # limitations under the License. # # %CopyrightEnd% -# +# SPECS_ESRC = ../../preloaded/src/ @@ -52,29 +52,28 @@ XML_REF3_EFILES = \ erlang.xml \ erl_tracer.xml \ init.xml \ + persistent_term.xml \ + atomics.xml \ + counters.xml \ zlib.xml XML_REF3_FILES = \ + $(XML_REF3_EFILES) \ driver_entry.xml \ erl_nif.xml \ - erl_tracer.xml \ erl_driver.xml \ - erl_prim_loader.xml \ - erlang.xml \ - erts_alloc.xml \ - init.xml \ - zlib.xml + erts_alloc.xml XML_PART_FILES = \ - part.xml \ - part_notes.xml \ - part_notes_history.xml + part.xml XML_CHAPTER_FILES = \ + introduction.xml \ tty.xml \ match_spec.xml \ crash_dump.xml \ alt_dist.xml \ + alt_disco.xml \ driver.xml \ absform.xml \ inet_cfg.xml \ @@ -82,8 +81,7 @@ XML_CHAPTER_FILES = \ erl_dist_protocol.xml \ communication.xml \ time_correction.xml \ - notes.xml \ - notes_history.xml + notes.xml TOPDOCDIR=../../../doc @@ -116,9 +114,9 @@ SPECS_FILES = $(XML_REF3_EFILES:%.xml=$(SPECDIR)/specs_%.xml) TOP_SPECS_FILE = specs.xml # ---------------------------------------------------- -# FLAGS +# FLAGS # ---------------------------------------------------- -XML_FLAGS += +XML_FLAGS += KERNEL_SRC=$(ERL_TOP)/lib/kernel/src KERNEL_INCLUDE=$(ERL_TOP)/lib/kernel/include @@ -146,23 +144,24 @@ $(INFO_FILE): $(INFO_FILE_SRC) $(ERL_TOP)/make/$(TARGET)/otp.mk sed -e 's;%RELEASE%;$(SYSTEM_VSN);' $(INFO_FILE_SRC) > $(INFO_FILE) -debug opt: +debug opt: clean: rm -rf $(HTMLDIR)/* + rm -rf $(XMLDIR) rm -f $(MAN1DIR)/* rm -f $(MAN3DIR)/* rm -f $(TOP_PDF_FILE) $(TOP_PDF_FILE:%.pdf=%.fo) rm -f $(SPECDIR)/* - rm -f errs core *~ + rm -f errs core *~ $(SPECDIR)/specs_%.xml: - escript $(SPECS_EXTRACTOR) $(SPECS_FLAGS) \ + $(gen_verbose)escript $(SPECS_EXTRACTOR) $(SPECS_FLAGS) \ -o$(dir $@) -module $(patsubst $(SPECDIR)/specs_%.xml,%,$@) # ---------------------------------------------------- # Release Target -# ---------------------------------------------------- +# ---------------------------------------------------- include $(ERL_TOP)/make/otp_release_targets.mk release_docs_spec: docs @@ -173,6 +172,8 @@ release_docs_spec: docs "$(RELSYSDIR)/doc/html" $(INSTALL_DATA) $(ERL_TOP)/erts/example/time_compat.erl \ "$(RELSYSDIR)/doc/html" + $(INSTALL_DATA) $(ERL_TOP)/lib/kernel/examples/gen_tcp_dist/src/gen_tcp_dist.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 ab00d47425..d77d989057 100644 --- a/erts/doc/src/absform.xml +++ b/erts/doc/src/absform.xml @@ -4,7 +4,7 @@ <chapter> <header> <copyright> - <year>2001</year><year>2016</year> + <year>2001</year><year>2018</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -182,10 +182,18 @@ can contain the following:</p> <list type="bulleted"> - <item>Tuples <c>{error,E}</c> and <c>{warning,W}</c>, denoting - syntactically incorrect forms and warnings</item> - <item><c>{eof,LINE}</c>, denoting an end-of-stream - encountered before a complete form had been parsed</item> + <item> + <p>Tuples <c>{error,E}</c> and <c>{warning,W}</c>, denoting + syntactically incorrect forms and warnings. + </p> + </item> + <item> + <p><c>{eof,LOCATION}</c>, denoting an end-of-stream + encountered before a complete form had been parsed. + The word <c>LOCATION</c> represents an integer, and denotes the + number of the last line in the source file. + </p> + </item> </list> </section> </section> @@ -357,7 +365,7 @@ <c>{cons,LINE,Rep(E_h),Rep(E_t)}</c>.</p> </item> <item> - <p>>If E is a fun expression <c>fun Name/Arity</c>, then Rep(E) = + <p>If E is a fun expression <c>fun Name/Arity</c>, then Rep(E) = <c>{'fun',LINE,{function,Name,Arity}}</c>.</p> </item> <item> @@ -399,9 +407,8 @@ </item> <item> <p>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>. + where each <c>A_i</c> is an association <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.</p> </item> <item> @@ -606,26 +613,58 @@ <item> <p>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>.</p> + Rep(C) = <c>{clause,LINE,[Rep({throw,P,_})],[],Rep(B)}</c>, + that is, a catch clause with an explicit exception class + <c>throw</c> and with or without an explicit stacktrace + variable <c>_</c> cannot be distinguished from a catch clause + without an explicit exception class and without an explicit + stacktrace variable.</p> </item> <item> <p>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>.</p> + Rep(C) = <c>{clause,LINE,[Rep({X,P,_})],[],Rep(B)}</c>, + that is, a catch clause with an explicit exception class and + with an explicit stacktrace variable <c>_</c> cannot be + distinguished from a catch clause with an explicit exception + class and without an explicit stacktrace variable.</p> + </item> + <item> + <p>If C is a catch clause <c>X : P : S -> B</c>, + where <c>X</c> is an atomic literal or a variable pattern, + <c>P</c> is a pattern, <c>S</c> is a variable, and <c>B</c> + is a body, then + Rep(C) = <c>{clause,LINE,[Rep({X,P,S})],[],Rep(B)}</c>.</p> </item> <item> <p>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>.</p> + Rep(C) = <c>{clause,LINE,[Rep({throw,P,_})],Rep(Gs),Rep(B)}</c>, + that is, a catch clause with an explicit exception class + <c>throw</c> and with or without an explicit stacktrace + variable <c>_</c> cannot be distinguished from a catch clause + without an explicit exception class and without an explicit + stacktrace variable.</p> </item> <item> <p>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>.</p> + Rep(C) = <c>{clause,LINE,[Rep({X,P,_})],Rep(Gs),Rep(B)}</c>, + that is, a catch clause with an explicit exception class and + with an explicit stacktrace variable <c>_</c> cannot be + distinguished from a catch clause with an explicit exception + class and without an explicit stacktrace variable.</p> + </item> + <item> + <p>If C is a catch clause <c>X : P : S 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, + <c>S</c> is a variable, and <c>B</c> is a body, then + Rep(C) = <c>{clause,LINE,[Rep({X,P,S})],Rep(Gs),Rep(B)}</c>.</p> </item> <item> <p>If C is a function clause <c>( Ps ) -> B</c>, @@ -691,9 +730,8 @@ </item> <item> <p>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>. + where each <c>A_i</c> is an association <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.</p> </item> <item> @@ -763,7 +801,8 @@ <c>{ann_type,LINE,[Rep(A),Rep(T_0)]}</c>.</p> </item> <item> - <p>If T is an atom or integer literal L, then Rep(T) = Rep(L).</p> + <p>If T is an atom, a character, or an integer literal L, + then Rep(T) = Rep(L).</p> </item> <item> <p>If T is a bitstring type <c><<_:M,_:_*N>></c>, @@ -772,7 +811,9 @@ </item> <item> <p>If T is the empty list type <c>[]</c>, then Rep(T) = - <c>{type,Line,nil,[]}</c>.</p> + <c>{type,Line,nil,[]}</c>, that is, the empty list type + <c>[]</c> cannot be distinguished from the predefined type + <c>nil()</c>.</p> </item> <item> <p>If T is a fun type <c>fun()</c>, then Rep(T) = @@ -886,7 +927,7 @@ 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>, + <item>If C is a constraint <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>. diff --git a/erts/doc/src/alt_disco.xml b/erts/doc/src/alt_disco.xml new file mode 100644 index 0000000000..d04221b9b3 --- /dev/null +++ b/erts/doc/src/alt_disco.xml @@ -0,0 +1,93 @@ +<?xml version="1.0" encoding="utf-8" ?> +<!DOCTYPE chapter SYSTEM "chapter.dtd"> + +<chapter> + <header> + <copyright> + <year>2018</year><year>2018</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>How to Implement an Alternative Service Discovery for Erlang Distribution + </title> + <prepared>Timmo Verlaan</prepared> + <responsible></responsible> + <docno></docno> + <approved></approved> + <checked></checked> + <date>2018-04-25</date> + <rev>PA1</rev> + <file>alt_disco.xml</file> + </header> + <p> + This section describes how to implement an alternative discovery mechanism + for Erlang distribution. Discovery is normally done using DNS and the + Erlang Port Mapper Daemon (EPMD) for port discovery. + </p> + + <note><p> + Support for alternative service discovery mechanisms was added in Erlang/OTP + 21. + </p></note> + + + <section> + <title>Introduction</title> + <p>To implement your own service discovery module you have to write your own + EPMD module. The <seealso marker="kernel:erl_epmd">EPMD module</seealso> is + responsible for providing the location of another node. The distribution + modules (<c>inet_tcp_dist</c>/<c>inet_tls_dist</c>) call the EPMD module to + get the IP address and port of the other node. The EPMD module that is part + of Erlang/OTP will resolve the hostname using DNS and uses the EPMD unix + process to get the port of another node. The EPMD unix process does this by + connecting to the other node on a well-known port, port 4369.</p> + </section> + + <section> + <title>Discovery module</title> + <p>The discovery module needs to implement the same API as the regular + <seealso marker="kernel:erl_epmd">EPMD module</seealso>. However, instead of + communicating with EPMD you can connect to any service to find out + connection details of other nodes. A discovery module is enabled + by setting <seealso marker="erts:erl#epmd_module">-epmd_module</seealso> + when starting erlang. The discovery module must implement the following + callbacks:</p> + + <taglist> + <tag><seealso marker="kernel:erl_epmd#start_link/0">start_link/0</seealso></tag> + <item>Start any processes needed by the discovery module.</item> + <tag><seealso marker="kernel:erl_epmd#names/1">names/1</seealso></tag> + <item>Return node names held by the registrar for the given host.</item> + <tag><seealso marker="kernel:erl_epmd#register_node/2">register_node/2</seealso></tag> + <item>Register the given node name with the registrar.</item> + <tag><seealso marker="kernel:erl_epmd#port_please/3">port_please/3</seealso></tag> + <item>Return the distribution port used by the given node.</item> + </taglist> + + <p>The discovery module may implement the following callback:</p> + + <taglist> + <tag><seealso marker="kernel:erl_epmd#address_please/3">address_please/3</seealso></tag> + <item><p>Return the address of the given node. + If not implemented, <seealso marker="kernel:inet#gethostbyname/1"> + inet:gethostbyname/1</seealso> will be used instead</p> + <p>This callback may also return the port of the given node. In that case + <seealso marker="kernel:erl_epmd#port_please/3">port_please/3</seealso> + may be omitted.</p></item> + </taglist> + </section> +</chapter> diff --git a/erts/doc/src/alt_dist.xml b/erts/doc/src/alt_dist.xml index be969a8267..e6245130fc 100644 --- a/erts/doc/src/alt_dist.xml +++ b/erts/doc/src/alt_dist.xml @@ -4,7 +4,7 @@ <chapter> <header> <copyright> - <year>2000</year><year>2016</year> + <year>2000</year><year>2018</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -47,23 +47,30 @@ runs on. The reason the C code is not made portable, is simply readability.</p> - <note> - <p>This section was written a long time ago. Most of it is still - valid, but some things have changed since then. - Most notably is the driver interface. Some updates have been made - to the documentation of the driver presented here, - but more can be done and is planned for the future. - The reader is encouraged to read the - <seealso marker="erl_driver"><c>erl_driver</c></seealso> and - <seealso marker="driver_entry"><c>driver_entry</c></seealso> - documentation also.</p> - </note> - <section> <title>Introduction</title> <p>To implement a new carrier for the Erlang distribution, the main steps are as follows.</p> + <note><p> + As of ERTS version 10.0 support for distribution controller + processes has been introduced. That is, the traffic over a + distribution channel can be managed by a process instead of + only by a port. This makes it possible to implement large + parts of the logic in Erlang code, and you perhaps do not + even need a new driver for the protocol. One example could + be Erlang distribution over UDP using <c>gen_udp</c> (your + Erlang code will of course have to take care of retranspissions, + etc in this example). That is, depending on what you want + to do you perhaps do not need to implement a driver at all + and can then skip the driver related sections below. + The <c>gen_tcp_dist</c> example described in the + <seealso marker="#distribution_module">Distribution + Module</seealso> section utilize distribution controller + processes and can be worth having a look at if you want to + use distribution controller processes. + </p></note> + <section> <title>Writing an Erlang Driver</title> <p>First, the protocol must be available to the Erlang machine, which @@ -152,7 +159,711 @@ </section> <section> + <marker id="distribution_module"/> + <title>Distribution Module</title> + <p> + The distribution module expose an API that <c>net_kernel</c> call + in order to manage connections to other nodes. The module name + should have the suffix <c>_dist</c>. + </p> + <p> + The module needs to create some kind of listening entity (process + or port) and an acceptor process that accepts incoming connections + using the listening entity. For each connection, the module at least + needs to create one connection supervisor process, which also is + responsible for the handshake when setting up the connection, and + a distribution controller (process or port) responsible for + transport of data over the connection. The distribution controller + and the connection supervisor process should be linked together + so both of them are cleaned up when the connection is taken down. + </p> + <p> + Note that there need to be exactly one distribution controller + per connection. A process or port can only be distribution + controller for one connection. The registration as distribution + controller cannot be undone. It will stick until the distribution + controller terminates. The distribution controller should not + ignore exit signals. It is allowed to trap exits, but it should + then voluntarily terminate when an exit signal is received. + </p> + <p> + An example implementation of a distribution module can be found + in + <url href="gen_tcp_dist.erl">$ERL_TOP/lib/kernel/examples/gen_tcp_dist/src/gen_tcp_dist.erl</url>. + It implements the distribution over TCP/IP using the <c>gen_tcp</c> + API with distribution controllers implemented by processes. This + instead of using port distribution controllers as the ordinary TCP/IP + distribution uses. + </p> + + <section> + <marker id="distribution_module_exported_callback_functions"/> + <title>Exported Callback Functions</title> + + <p> + The following functions are mandatory: + </p> + <taglist> + <tag><marker id="listen"/><c>listen(Name) -></c><br/> <c>{ok, {Listen, Address, Creation}} | {error, Error} </c></tag> + <item> + <p> + <c>listen/1</c> is called once in order to listen for incoming + connection requests. The call is made when the distribution is brought + up. The argument <c>Name</c> is the part of the node name before + the <c>@</c> sign in the full node name. It can be either an atom or a + string. + </p> + <p> + The return value consists of a <c>Listen</c> handle (which is + later passed to the <seealso marker="#accept"><c>accept/1</c></seealso> + callback), <c>Address</c> which is a <c>#net_address{}</c> record + with information about the address for the node (the + <c>#net_address{}</c> record is defined in + <c>kernel/include/net_address.hrl</c>), and <c>Creation</c> which + (currently) is an integer <c>1</c>, <c>2</c>, or <c>3</c>. + </p> + <p> + If <seealso marker="erts:epmd"><c>epmd</c></seealso> is to be used + for node discovery, you typically want to use the (unfortunately + undocumented) <c>erl_epmd</c> module (part of the <c>kernel</c> + application) in order to register the listen port with <c>epmd</c> + and retrieve <c>Creation</c> to use. + </p> + </item> + + <tag><marker id="accept"/><c>accept(Listen) -></c><br/> <c>AcceptorPid</c></tag> + <item> + <p> + <c>accept/1</c> should spawn a process that accepts connections. This + process should preferably execute on <c>max</c> priority. The process + identifier of this process should be returned. + </p> + <p> + The <c>Listen</c> argument will be the same as the <c>Listen</c> handle + part of the return value of the + <seealso marker="#listen"><c>listen/1</c></seealso> callback above. + <c>accept/1</c> is called only once when the distribution protocol is + started. + </p> + <p> + The caller of this function is a representative for <c>net_kernel</c> + (this may or may not be the process registered as <c>net_kernel</c>) + and is in this document identified as <c>Kernel</c>. + When a connection has been accepted by the acceptor process, it needs + to inform <c>Kernel</c> about the accepted connection. This is done by + passing a message on the form: + </p> + <code type="none"><![CDATA[Kernel ! {accept, AcceptorPid, DistController, Family, Proto}]]></code> + <p> + <c>DistController</c> is either the process or port identifier + of the distribution controller for the connection. The + distribution controller should be created by the acceptor + processes when a new connection is accepted. Its job is to + dispatch traffic on the connection. + </p> + <c>Kernel</c> responds with one of the following messages: + <taglist> + <tag><c>{Kernel, controller, SupervisorPid}</c></tag> + <item> + <p> + The request was accepted and <c>SupervisorPid</c> is the + process identifier of the connection supervisor process + (which is created in the + <seealso marker="#accept_connection"><c>accept_connection/5</c></seealso> + callback). + </p> + </item> + <tag><c>{Kernel, unsupported_protocol}</c></tag> + <item> + <p> + The request was rejected. This is a fatal error. The acceptor + process should terminate. + </p> + </item> + </taglist> + <p> + When an accept sequence has been completed the acceptor process + is expected to continue accepting further requests. + </p> + </item> + + <tag><marker id="accept_connection"/><c>accept_connection(AcceptorPid, DistCtrl, MyNode, Allowed, SetupTime) -></c><br/> <c>ConnectionSupervisorPid</c></tag> + <item> + <p> + <c>accept_connection/5</c> should spawn a process that will + perform the Erlang distribution handshake for the connection. + If the handshake successfully completes it should continue to + function as a connection supervisor. This process + should preferably execute on <c>max</c> priority. + </p> + <p>The arguments:</p> + <taglist> + <tag><c>AcceptorPid</c></tag> + <item> + <p> + Process identifier of the process created by the + <seealso marker="#accept"><c>accept/1</c></seealso> + callback. + </p> + </item> + <tag><c>DistCtrl</c></tag> + <item> + <p>The identifier of the distribution controller identifier + created by the acceptor process. To be passed along to + <c>dist_util:handshake_other_started(HsData)</c>. + </p> + </item> + <tag><c>MyNode</c></tag> + <item> + <p> + Node name of this node. To be passed along to + <c>dist_util:handshake_other_started(HsData)</c>. + </p> + </item> + <tag><c>Allowed</c></tag> + <item> + <p> + To be passed along to + <c>dist_util:handshake_other_started(HsData)</c>. + </p> + </item> + <tag><c>SetupTime</c></tag> + <item> + <p> + Time used for creating a setup timer by a + call to <c>dist_util:start_timer(SetupTime)</c>. + The timer should be passed along to + <c>dist_util:handshake_other_started(HsData)</c>. + </p> + </item> + </taglist> + <p> + The created process should provide callbacks and other + information needed for the handshake in a + <seealso marker="#hs_data_record"><c>#hs_data{}</c></seealso> + record and call <c>dist_util:handshake_other_started(HsData)</c> + with this record. + </p> + <p> + <c>dist_util:handshake_other_started(HsData)</c> will perform + the handshake and if the handshake successfully completes this + process will then continue in a connection supervisor loop + as long as the connection is up. + </p> + </item> + + <tag><marker id="setup"/><c>setup(Node, Type, MyNode, LongOrShortNames, SetupTime) -></c><br/> <c>ConnectionSupervisorPid</c></tag> + <item> + <p> + <c>setup/5</c> should spawn a process that connects to + <c>Node</c>. When connection has been established it should + perform the Erlang distribution handshake for the connection. + If the handshake successfully completes it should continue to + function as a connection supervisor. This process + should preferably execute on <c>max</c> priority. + </p> + <p>The arguments:</p> + <taglist> + <tag><c>Node</c></tag> + <item> + <p> + Node name of remote node. To be passed along to + <c>dist_util:handshake_we_started(HsData)</c>. + </p> + </item> + <tag><c>Type</c></tag> + <item> + <p> + Connection type. To be passed along to + <c>dist_util:handshake_we_started(HsData)</c>. + </p> + </item> + <tag><c>MyNode</c></tag> + <item> + <p> + Node name of this node. To be passed along to + <c>dist_util:handshake_we_started(HsData)</c>. + </p> + </item> + <tag><c>LongOrShortNames</c></tag> + <item> + <p> + Either the atom <c>longnames</c> or + the atom <c>shortnames</c> indicating + whether long or short names is used. + </p> + </item> + <tag><c>SetupTime</c></tag> + <item> + <p> + Time used for creating a setup timer by a + call to <c>dist_util:start_timer(SetupTime)</c>. + The timer should be passed along to + <c>dist_util:handshake_we_started(HsData)</c>. + </p> + </item> + </taglist> + <p> + The caller of this function is a representative for <c>net_kernel</c> + (this may or may not be the process registered as <c>net_kernel</c>) + and is in this document identified as <c>Kernel</c>. + </p> + <p> + This function should, besides spawning the connection supervisor, + also create a distribution controller. The distribution + controller is either a process or a port which is responsible + for dispatching traffic. + </p> + <p> + The created process should provide callbacks and other + information needed for the handshake in a + <seealso marker="#hs_data_record"><c>#hs_data{}</c></seealso> + record and call <c>dist_util:handshake_we_started(HsData)</c> + with this record. + </p> + <p> + <c>dist_util:handshake_we_started(HsData)</c> will perform + the handshake and the handshake successfully completes this + process will then continue in a connection supervisor loop + as long as the connection is up. + </p> + </item> + + <tag><marker id="close"/><c>close(Listen) -></c><br/> <c>void()</c></tag> + + <item><p> + Called in order to close the <c>Listen</c> handle + that originally was passed from the + <seealso marker="#listen"><c>listen/1</c></seealso> callback. + </p></item> + + <tag><marker id="select"/><c>select(NodeName) -></c><br/> <c>boolean()</c></tag> + <item> + <p>Return <c>true</c> if the host name part + of the <c>NodeName</c> is valid for use + with this protocol; otherwise, <c>false</c>. + </p> + </item> + + </taglist> + + <p> + There are also two optional functions that may be + exported: + </p> + <taglist> + <tag><marker id="select"/><c>setopts(Listen, Opts) -></c><br/> <c>ok | {error, Error}</c></tag> + <item> + <p> + The argument <c>Listen</c> is the handle originally passed + from the + <seealso marker="#listen"><c>listen/1</c></seealso> callback. + The argument <c>Opts</c> is a list of options to set on future + connections. + </p> + </item> + + <tag><marker id="select"/><c>getopts(Listen, Opts) -></c><br/> <c>{ok, OptionValues} | {error, Error}</c></tag> + <item> + <p> + The argument <c>Listen</c> is the handle originally passed + from the + <seealso marker="#listen"><c>listen/1</c></seealso> callback. + The argument <c>Opts</c> is a list of options to read for future + connections. + </p> + </item> + </taglist> + + </section> + <section> + <marker id="hs_data_record"/> + <title>The #hs_data{} Record</title> + <p> + The <c>dist_util:handshake_we_started/1</c> and + <c>dist_util:handshake_other_started/1</c> functions + takes a <c>#hs_data{}</c> record as argument. There + are quite a lot of fields in this record that you + need to set. The record is defined in + <c>kernel/include/dist_util.hrl</c>. Not documented + fields should not be set, i.e., should be left as + <c>undefined</c>. + </p> + <p> + The following <c>#hs_data{}</c> record fields need + to be set unless otherwise stated:</p> + <taglist> + <tag><marker id="hs_data_kernel_pid"/><c>kernel_pid</c></tag> + <item> + <p> + Process identifier of the <c>Kernel</c> process. That is, + the process that called either + <seealso marker="#setup"><c>setup/5</c></seealso> or + <seealso marker="#accept_connection"><c>accept_connection/5</c></seealso>. + </p> + </item> + + <tag><marker id="hs_data_other_node"/><c>other_node</c></tag> + <item> + <p>Name of the other node. This field is only + mandatory when this node initiates the connection. + That is, when connection is set up via + <seealso marker="#setup"><c>setup/5</c></seealso>. + </p> + </item> + + <tag><marker id="hs_data_this_node"/><c>this_node</c></tag> + <item> + <p> + The node name of this node. + </p> + </item> + + <tag><marker id="hs_data_socket"/><c>socket</c></tag> + <item> + <p> + The identifier of the distribution controller. + </p> + </item> + + <tag><marker id="hs_data_timer"/><c>timer</c></tag> + <item> + <p> + The timer created using <c>dist_util:start_timer/1</c>. + </p> + </item> + + <tag><marker id="hs_data_allowed"/><c>allowed</c></tag> + <item> + <p>Information passed as <c>Allowed</c> to + <c>accept_connection/5</c>. This field is only + mandatory when the remote node initiated the + connection. That is, when the connection is set + up via + <seealso marker="#accept_connection"><c>accept_connection/5</c></seealso>. + </p> + </item> + + <tag><marker id="hs_data_f_send"/><c>f_send</c></tag> + <item> + <p> + A fun with the following signature: + </p> + <code type="none"><![CDATA[fun (DistCtrlr, Data) -> ok | {error, Error}]]></code> + <p> + where <c>DistCtrlr</c> is the identifier of + the distribution controller and <c>Data</c> + is io data to pass to the other side. + </p> + <p>Only used during handshake phase.</p> + </item> + + <tag><marker id="hs_data_f_recv"/><c>f_recv</c></tag> + <item> + <p> + A fun with the following signature: + </p> + <code type="none"><![CDATA[fun (DistCtrlr, Length) -> {ok, Packet} | {error, Reason}]]></code> + <p> + where <c>DistCtrlr</c> is the identifier of the distribution + controller. + If <c>Length</c> is <c>0</c>, all available bytes should be + returned. If <c>Length > 0</c>, exactly <c>Length</c> bytes + should be returned, or an error; possibly discarding less + than <c>Length</c> bytes of data when the connection is + closed from the other side. + It is used for passive receive of data from the + other end. + </p> + <p>Only used during handshake phase.</p> + </item> + + <tag><marker id="hs_data_f_setopts_pre_nodeup"/><c>f_setopts_pre_nodeup</c></tag> + <item> + <p> + A fun with the following signature: + </p> + <code type="none"><![CDATA[fun (DistCtrlr) -> ok | {error, Error}]]></code> + <p> + where <c>DistCtrlr</c> is the identifier of + the distribution controller. Called just + before the distribution channel is taken up + for normal traffic. + </p> + <p>Only used during handshake phase.</p> + </item> + + <tag><marker id="hs_data_f_setopts_post_nodeup"/><c>f_setopts_post_nodeup</c></tag> + <item> + <p> + A fun with the following signature: + </p> + <code type="none"><![CDATA[fun (DistCtrlr) -> ok | {error, Error}]]></code> + <p> + where <c>DistCtrlr</c> is the identifier of + the distribution controller. Called just + after distribution channel has been taken + up for normal traffic. + </p> + <p>Only used during handshake phase.</p> + </item> + + <tag><marker id="hs_data_f_getll"/><c>f_getll</c></tag> + <item> + <p> + A fun with the following signature: + </p> + <code type="none"><![CDATA[fun (DistCtrlr) -> ID]]></code> + <p> + where <c>DistCtrlr</c> is the identifier of + the distribution controller and <c>ID</c> is + the identifier of the low level entity that + handles the connection (often <c>DistCtrlr</c> + itself). + </p> + <p>Only used during handshake phase.</p> + </item> + + <tag><marker id="hs_data_f_address"/><c>f_address</c></tag> + <item> + <p> + A fun with the following signature: + </p> + <code type="none"><![CDATA[fun (DistCtrlr, Node) -> NetAddress]]></code> + <p> + where <c>DistCtrlr</c> is the identifier of + the distribution controller, <c>Node</c> + is the node name of the node on the other end, + and <c>NetAddress</c> is a <c>#net_address{}</c> + record with information about the address + for the <c>Node</c> on the other end of the + connection. The <c>#net_address{}</c> record + is defined in + <c>kernel/include/net_address.hrl</c>. + </p> + <p>Only used during handshake phase.</p> + </item> + + <tag><marker id="hs_data_mf_tick"/><c>mf_tick</c></tag> + <item> + <p> + A fun with the following signature: + </p> + <code type="none"><![CDATA[fun (DistCtrlr) -> void()]]></code> + <p> + where <c>DistCtrlr</c> is the identifier + of the distribution controller. This + function should send information over + the connection that is not interpreted + by the other end while increasing the + statistics of received packets on the + other end. This is usually implemented by + sending an empty packet. + </p> + <note><p> + It is of vital importance that this operation + does not block the caller for a long time. + This since it is called from the connection + supervisor. + </p></note> + <p>Used when connection is up.</p> + </item> + + <tag><marker id="hs_data_mf_getstat"/><c>mf_getstat</c></tag> + <item> + <p> + A fun with the following signature: + </p> + <code type="none"><![CDATA[fun (DistCtrlr) -> {ok, Received, Sent, PendSend}]]></code> + <p> + where <c>DistCtrlr</c> is the identifier + of the distribution controller, <c>Received</c> + is received packets, <c>Sent</c> is + sent packets, and <c>PendSend</c> is + amount of packets in queue to be sent + or a <c>boolean()</c> indicating whether + there are packets in queue to be sent. + </p> + <note><p> + It is of vital importance that this operation + does not block the caller for a long time. + This since it is called from the connection + supervisor. + </p></note> + <p>Used when connection is up.</p> + </item> + + <tag><marker id="hs_data_request_type"/><c>request_type</c></tag> + <item> + <p> + The request <c>Type</c> as passed to + <seealso marker="#setup"><c>setup/5</c></seealso>. + This is only mandatory when the connection has + been initiated by this node. That is, the connection + is set up via <c>setup/5</c>. + </p> + </item> + + <tag><marker id="hs_data_mf_setopts"/><c>mf_setopts</c></tag> + <item> + <p> + A fun with the following signature: + </p> + <code type="none"><![CDATA[fun (DistCtrl, Opts) -> ok | {error, Error}]]></code> + <p> + where <c>DistCtrlr</c> is the identifier + of the distribution controller and <c>Opts</c> + is a list of options to set on the connection. + </p> + <p>This function is optional. Used when connection is up.</p> + </item> + + <tag><marker id="hs_data_mf_getopts"/><c>mf_getopts</c></tag> + <item> + <p> + A fun with the following signature: + </p> + <code type="none"><![CDATA[fun (DistCtrl, Opts) -> {ok, OptionValues} | {error, Error}]]></code> + <p> + where <c>DistCtrlr</c> is the identifier + of the distribution controller and <c>Opts</c> + is a list of options to read for the connection. + </p> + <p>This function is optional. Used when connection is up.</p> + </item> + + <tag><marker id="hs_data_f_handshake_complete"/><c>f_handshake_complete</c></tag> + <item> + <p> + A fun with the following signature: + </p> + <code type="none"><![CDATA[fun (DistCtrlr, Node, DHandle) -> void()]]></code> + <p> + where <c>DistCtrlr</c> is the identifier + of the distribution controller, <c>Node</c> is + the node name of the node connected at the other + end, and <c>DHandle</c> is a distribution handle + needed by a distribution controller process when + calling the following BIFs: + </p> + <list> + <item><p><seealso marker="erts:erlang#dist_ctrl_get_data/1"><c>erlang:dist_ctrl_get_data/1</c></seealso></p></item> + <item><p><seealso marker="erts:erlang#dist_ctrl_get_data_notification/1"><c>erlang:dist_ctrl_get_data_notification/1</c></seealso></p></item> + <item><p><seealso marker="erts:erlang#dist_ctrl_input_handler/2"><c>erlang:dist_ctrl_input_handler/2</c></seealso></p></item> + <item><p><seealso marker="erts:erlang#dist_ctrl_put_data/2"><c>erlang:dist_ctrl_put_data/2</c></seealso></p></item> + </list> + <p> + This function is called when the handshake has + completed and the distribution channel is up. + The distribution controller can begin dispatching + traffic over the channel. This function is optional. + </p> + <p>Only used during handshake phase.</p> + </item> + + <tag><marker id="hs_data_add_flags"/><c>add_flags</c></tag> + <item> + <p> + <seealso marker="erl_dist_protocol#dflags">Distribution flags</seealso> + to add to the connection. Currently all (non obsolete) flags will + automatically be enabled. + </p> + <p> + This flag field is optional. + </p> + </item> + + <tag><marker id="hs_data_reject_flags"/><c>reject_flags</c></tag> + <item> + <p> + <seealso marker="erl_dist_protocol#dflags">Distribution flags</seealso> + to reject. Currently the following distribution flags can be rejected: + </p> + <taglist> + <tag><c>DFLAG_DIST_HDR_ATOM_CACHE</c></tag> + <item>Do not use atom cache over this connection.</item> + </taglist> + <p>Use function <c>dist_util:strict_order_flags/0</c> to get all flags + for features that require strict order delivery.</p> + <p> + This flag field is optional. + </p> + </item> + + <tag><marker id="hs_data_require_flags"/><c>require_flags</c></tag> + <item> + <p> + Require these <seealso marker="erl_dist_protocol#dflags">distribution + flags</seealso> to be used. The connection will be aborted during the + handshake if the other end does not use them. + </p> + <p> + This flag field is optional. + </p> + </item> + + </taglist> + </section> + + <section> + <marker id="distribution_data_delivery"/> + <title>Distribution Data Delivery</title> + <p> + When using the default configuration, the data to pass + over a connection needs to be delivered as is + to the node on the receiving end in the <em>exact same + order</em>, with no loss of data what so ever, as sent + from the sending node. + </p> + <p> + The data delivery order can be relaxed by disabling + features that require strict ordering. This is done by + passing the + <seealso marker="erl_dist_protocol#dflags">distribution flags</seealso> + returned by <c>dist_util:strict_order_flags/0</c> in the + <seealso marker="alt_dist#hs_data_reject_flags"><c>reject_flags</c></seealso> + field of the <seealso marker="#hs_data_record"><c>#hs_data{}</c></seealso> + record used when setting up the connection. When relaxed + ordering is used, only the order of signals with the same + sender/receiver pair has to be preserved. + However, note that disabling the features that require + strict ordering may have a negative impact on performance, + throughput, and/or latency. + </p> + </section> + + <section> + <marker id="enable_your_distribution_module"/> + <title>Enable Your Distribution Module</title> + + <p>For <c>net_kernel</c> to find out which distribution module to use, + the <c>erl</c> command-line argument <c>-proto_dist</c> is used. It + is followed by one or more distribution module names, with suffix + "_dist" removed. That is, <c>gen_tcp_dist</c> as a distribution module + is specified as <c>-proto_dist gen_tcp</c>.</p> + + <p>If no <c>epmd</c> (TCP port mapper daemon) is used, also command-line + option <c>-no_epmd</c> is to be specified, which makes + Erlang skip the <c>epmd</c> startup, both as an OS process and as an + Erlang ditto.</p> + </section> + + </section> + + <section> <title>The Driver</title> + + <note> + <p>This section was written a long time ago. Most of it is still + valid, but some things have changed since then. Some updates have + been made to the documentation of the driver presented here, + but more can be done and is planned for the future. + The reader is encouraged to read the + <seealso marker="erl_driver"><c>erl_driver</c></seealso> and + <seealso marker="driver_entry"><c>driver_entry</c></seealso> + documentation also.</p> + </note> + <p>Although Erlang drivers in general can be beyond the scope of this section, a brief introduction seems to be in place.</p> diff --git a/erts/doc/src/atomics.xml b/erts/doc/src/atomics.xml new file mode 100644 index 0000000000..455973f011 --- /dev/null +++ b/erts/doc/src/atomics.xml @@ -0,0 +1,185 @@ +<?xml version="1.0" encoding="utf-8" ?> +<!DOCTYPE erlref SYSTEM "erlref.dtd"> + +<erlref> + <header> + <copyright> + <year>2018</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>atomics</title> + </header> + <module since="OTP 21.2">atomics</module> + <modulesummary>Atomic Functions</modulesummary> + <description> + <p>This module provides a set of functions to do atomic operations towards + mutable atomic variables. The implementation utilizes only + atomic hardware instructions without any software level locking, which makes + it very efficient for concurrent access. The atomics are organized into + arrays with the following semantics:</p> + <list type="bulleted"> + <item> + <p>Atomics are 64 bit integers.</p> + </item> + <item> + <p>Atomics can be represented as either signed or unsigned.</p> + </item> + <item> + <p>Atomics wrap around at overflow and underflow operations.</p> + </item> + <item> + <p>All operations guarantee atomicity. No intermediate results can be + seen. The result of one mutation can only be the input to one + following mutation.</p> + </item> + <item> + <p>All atomic operations are mutually ordered. If atomic B is updated + <em>after</em> atomic A, then that is how it will appear to any + concurrent readers. No one can read the new value of B and then read the + old value of A.</p> + </item> + <item> + <p>Indexes into atomic arrays are one-based. An atomic array of + arity N contains N atomics with index from 1 to N.</p> + </item> + </list> + </description> + + <datatypes> + <datatype> + <name name="atomics_ref"/> + <desc><p>Identifies an atomic array returned from + <seealso marker="#new/2"><c>new/2</c></seealso>.</p> + </desc> + </datatype> + </datatypes> + + <funcs> + <func> + <name name="new" arity="2" since="OTP 21.2"/> + <fsummary>Create atomic array</fsummary> + <desc> + <p>Create a new atomic array of <c><anno>Arity</anno></c> atomics.</p> + <p>Argument <c><anno>Opts</anno></c> is a list of the following possible + options:</p> + <taglist> + <tag><c>{signed, boolean()}</c></tag> + <item><p>Indicate if the elements of the array will be treated + as signed or unsigned integers. Default is <c>true</c> (signed).</p> + <p>The integer interval for signed atomics are from <c>-(1 bsl 63)</c> + to <c>(1 bsl 63)-1</c> and for unsigned atomics from <c>0</c> to <c>(1 + bsl 64)-1</c>.</p> + </item> + </taglist> + <p>Atomics are not tied to the current process and are automatically + garbage collected when they are no longer referenced.</p> + </desc> + </func> + + <func> + <name name="put" arity="3" since="OTP 21.2"/> + <fsummary>Set atomic value</fsummary> + <desc> + <p>Set atomic to <c><anno>Value</anno></c>.</p> + </desc> + </func> + + <func> + <name name="get" arity="2" since="OTP 21.2"/> + <fsummary>Read atomic value</fsummary> + <desc> + <p>Read atomic value.</p> + </desc> + </func> + + <func> + <name name="add" arity="3" since="OTP 21.2"/> + <fsummary>Add to atomic</fsummary> + <desc> + <p>Add <c><anno>Incr</anno></c> to atomic.</p> + </desc> + </func> + + <func> + <name name="add_get" arity="3" since="OTP 21.2"/> + <fsummary>Atomic add and get</fsummary> + <desc> + <p>Atomic addition and return of the result.</p> + </desc> + </func> + + <func> + <name name="sub" arity="3" since="OTP 21.2"/> + <fsummary>Subtract from atomic</fsummary> + <desc> + <p>Subtract <c><anno>Decr</anno></c> from atomic.</p> + </desc> + </func> + + <func> + <name name="sub_get" arity="3" since="OTP 21.2"/> + <fsummary>Atomic sub and get</fsummary> + <desc> + <p>Atomic subtraction and return of the result.</p> + </desc> + </func> + + <func> + <name name="exchange" arity="3" since="OTP 21.2"/> + <fsummary>Atomic exchange.</fsummary> + <desc> + <p>Atomically replaces the value of the atomic with + <c><anno>Desired</anno></c> and returns the value it held + previously.</p> + </desc> + </func> + + <func> + <name name="compare_exchange" arity="4" since="OTP 21.2"/> + <fsummary>Atomic compare and exchange.</fsummary> + <desc> + <p>Atomically compares the atomic with <c><anno>Expected</anno></c>, + and if those are equal, set atomic to <c><anno>Desired</anno></c>. + Returns <c>ok</c> if <c><anno>Desired</anno></c> was written. Returns + the actual atomic value if not equal to <c><anno>Expected</anno></c>.</p> + </desc> + </func> + + <func> + <name name="info" arity="1" since="OTP 21.2"/> + <fsummary>Get information about atomic array.</fsummary> + <desc> + <p>Return information about an atomic array in a map. The map + has the following keys:</p> + <taglist> + <tag><c>size</c></tag> + <item><p>The number of atomics in the array.</p></item> + <tag><c>max</c></tag> + <item><p>The highest possible value an atomic in this array can + hold.</p></item> + <tag><c>min</c></tag> + <item><p>The lowest possible value an atomic in this array can + hold.</p></item> + <tag><c>memory</c></tag> + <item><p>Approximate memory consumption for the array in + bytes.</p></item> + </taglist> + </desc> + </func> + + </funcs> +</erlref> diff --git a/erts/doc/src/counters.xml b/erts/doc/src/counters.xml new file mode 100644 index 0000000000..36816bd68d --- /dev/null +++ b/erts/doc/src/counters.xml @@ -0,0 +1,172 @@ +<?xml version="1.0" encoding="utf-8" ?> +<!DOCTYPE erlref SYSTEM "erlref.dtd"> + +<erlref> + <header> + <copyright> + <year>2018</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>counters</title> + </header> + <module since="OTP 21.2">counters</module> + <modulesummary>Counter Functions</modulesummary> + <description> + <p>This module provides a set of functions to do operations towards + shared mutable counter variables. The implementation does not utilize any + software level locking, which makes it very efficient for concurrent + access. The counters are organized into arrays with the following + semantics:</p> + <list type="bulleted"> + <item> + <p>Counters are 64 bit signed integers.</p> + </item> + <item> + <p>Counters wrap around at overflow and underflow operations.</p> + </item> + <item><p>Counters are initialized to zero and can then only be written to + by adding or subtracting.</p> + </item> + <item> + <p>Write operations guarantee atomicity. No intermediate results can be + seen from a single write operation.</p> + </item> + <item> + <p>Two types of counter arrays can be created with options <c>atomics</c> or + <c>write_concurrency</c>. The <c>atomics</c> counters have good allround + performance with nice consistent semantics while + <c>write_concurrency</c> counters offers even better concurrent + write performance at the expense of some potential read + inconsistencies. See <seealso marker="#new/2"><c>new/2</c></seealso>.</p> + </item> + <item> + <p>Indexes into counter arrays are one-based. A counter array of + size N contains N counters with index from 1 to N.</p> + </item> + </list> + </description> + + <datatypes> + <datatype> + <name name="counters_ref"/> + <desc><p>Identifies a counter array returned from + <seealso marker="#new/2"><c>new/2</c></seealso>.</p> + </desc> + </datatype> + </datatypes> + + <funcs> + <func> + <name name="new" arity="2" since="OTP 21.2"/> + <fsummary>Create counter array</fsummary> + <desc> + <p>Create a new counter array of <c><anno>Size</anno></c> counters.</p> + <p>Argument <c><anno>Opts</anno></c> is a list of the following possible + options:</p> + <taglist> + <tag><c>atomics</c> (Default)</tag> + <item><p>Counters will be sequentially consistent. If write + operation A is done sequentially before write operation B, then a concurrent reader + may see none of them, only A, or both A and B. It cannot see only B.</p> + </item> + <tag><c>write_concurrency</c></tag> + <item><p>This is an optimization to achieve very efficient concurrent + <seealso marker="#add/3"><c>add</c></seealso> and <seealso + marker="#sub/3"><c>sub</c></seealso> operations at the expense of potential read + inconsistency and memory consumption per counter.</p> + <p>Read operations may see sequentially inconsistent results with + regard to concurrent write operations. Even if write operation A is done + sequentially before write operation B, a concurrent reader may see any + combination of A and B, including only B. A read operation is only + guaranteed to see all writes done sequentially before the read. No writes + are ever lost, but will eventually all be seen.</p> + <p>The typical use case for <c>write_concurrency</c> is when + concurrent calls to <seealso marker="#add/3"><c>add</c></seealso> and + <seealso marker="#sub/3"><c>sub</c></seealso> toward the same counters + are very frequent, while calls to <seealso marker="#get/2"><c>get</c> + </seealso> and <seealso marker="#put/3"><c>put</c></seealso> are much + less frequent. The lack of absolute read consistency must also be + acceptable.</p> + </item> + </taglist> + <p>Counters are not tied to the current process and are automatically + garbage collected when they are no longer referenced.</p> + </desc> + </func> + + <func> + <name name="get" arity="2" since="OTP 21.2"/> + <fsummary>Read counter value</fsummary> + <desc> + <p>Read counter value.</p> + </desc> + </func> + + <func> + <name name="add" arity="3" since="OTP 21.2"/> + <fsummary>Add to counter</fsummary> + <desc> + <p>Add <c><anno>Incr</anno></c> to counter at index + <c><anno>Ix</anno></c>.</p> + </desc> + </func> + + <func> + <name name="sub" arity="3" since="OTP 21.2"/> + <fsummary>Subtract from counter</fsummary> + <desc> + <p>Subtract <c><anno>Decr</anno></c> from counter at index + <c><anno>Ix</anno></c>.</p> + </desc> + </func> + + <func> + <name name="put" arity="3" since="OTP 21.2"/> + <fsummary>Set counter to value</fsummary> + <desc> + <p>Write <c><anno>Value</anno></c> to counter at index + <c><anno>Ix</anno></c>.</p> + <note> + <p>Despite its name, the <c>write_concurrency</c> optimization does not + improve <c>put</c>. A call to <c>put</c> is a relatively heavy + operation compared to the very lightweight and scalable <seealso + marker="#add/3"><c>add</c></seealso> and <seealso marker="#sub/3"> + <c>sub</c></seealso>. The cost for a <c>put</c> with + <c>write_concurrency</c> is like a <seealso marker="#get/2"><c>get</c> + </seealso> plus a <c>put</c> without <c>write_concurrency</c>.</p> + </note> + </desc> + </func> + + <func> + <name name="info" arity="1" since="OTP 21.2"/> + <fsummary>Get information about counter array.</fsummary> + <desc> + <p>Return information about a counter array in a map. The map + has the following keys (at least):</p> + <taglist> + <tag><c>size</c></tag> + <item><p>The number of counters in the array.</p></item> + <tag><c>memory</c></tag> + <item><p>Approximate memory consumption for the array in + bytes.</p></item> + </taglist> + </desc> + </func> + + </funcs> +</erlref> diff --git a/erts/doc/src/driver_entry.xml b/erts/doc/src/driver_entry.xml index 2421e0a8d9..fd7d6223f6 100644 --- a/erts/doc/src/driver_entry.xml +++ b/erts/doc/src/driver_entry.xml @@ -4,7 +4,7 @@ <cref> <header> <copyright> - <year>2001</year><year>2016</year> + <year>2001</year><year>2018</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -196,10 +196,7 @@ typedef struct erl_drv_entry { char **rbuf, ErlDrvSizeT rlen, unsigned int *flags); /* Works mostly like 'control', a synchronous call into the driver */ - void (*event)(ErlDrvData drv_data, ErlDrvEvent event, - ErlDrvEventData event_data); - /* Called when an event selected by - driver_event() has occurred */ + void* unused_event_callback; int extended_marker; /* ERL_DRV_EXTENDED_MARKER */ int major_version; /* ERL_DRV_EXTENDED_MAJOR_VERSION */ int minor_version; /* ERL_DRV_EXTENDED_MINOR_VERSION */ diff --git a/erts/doc/src/erl.xml b/erts/doc/src/erl.xml index 8da832ac37..05a9895687 100644 --- a/erts/doc/src/erl.xml +++ b/erts/doc/src/erl.xml @@ -4,7 +4,7 @@ <comref> <header> <copyright> - <year>1996</year><year>2016</year> + <year>1996</year><year>2018</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -239,6 +239,13 @@ <item> <p>Useful for debugging. Prints the arguments sent to the emulator.</p> </item> + <tag><c><![CDATA[-emu_type Type]]></c></tag> + <item> + <p>Start an emulator of a different type. For example, to start + the lock-counter emualator, use <c>-emu_type lcnt</c>. (The emulator + must already be built. Use the <c>configure</c> option + <c>--enable-lock-counter</c> to build the lock-counter emulator.)</p> + </item> <tag><c><![CDATA[-env Variable Value]]></c></tag> <item> <p>Sets the host OS environment variable <c><![CDATA[Variable]]></c> to @@ -353,11 +360,12 @@ </item> <tag><c><![CDATA[-mode interactive | embedded]]></c></tag> <item> - <p>Indicates if the system is to load code dynamically - (<c><![CDATA[interactive]]></c>), or if all code is to be loaded - during system initialization (<c><![CDATA[embedded]]></c>); see - <seealso marker="kernel:code"><c>code(3)</c></seealso>. - Defaults to <c><![CDATA[interactive]]></c>.</p> + <p>Modules are auto loaded when they are first referenced if the + runtime system runs in <c><![CDATA[interactive]]></c> mode, which is + the default. In <c><![CDATA[embedded]]></c> mode modules are not auto + loaded. The latter is recommended when the boot script preloads all + modules, as conventionally happens in OTP releases. See + <seealso marker="kernel:code"><c>code(3)</c></seealso></p>. </item> <tag><c><![CDATA[-name Name]]></c></tag> <item> @@ -372,6 +380,16 @@ <c><![CDATA[Host]]></c> is the fully qualified host name of the current host. For short names, use flag <c><![CDATA[-sname]]></c> instead.</p> + <warning> + <p> + Starting a distributed node without also specifying + <seealso marker="#proto_dist"><c>-proto_dist inet_tls</c></seealso> + will expose the node to attacks that may give the attacker + complete access to the node and in extension the cluster. + When using un-secure distributed nodes, make sure that the + network is configured to keep potential attackers out. + </p> + </warning> </item> <tag><c><![CDATA[-noinput]]></c></tag> <item> @@ -421,12 +439,17 @@ </item> <tag><c><![CDATA[-proto_dist Proto]]></c></tag> <item> + <marker id="proto_dist"/> <p>Specifies a protocol for Erlang distribution:</p> <taglist> <tag><c>inet_tcp</c></tag> <item>TCP over IPv4 (the default)</item> <tag><c>inet_tls</c></tag> - <item>Distribution over TLS/SSL</item> + <item>Distribution over TLS/SSL, See the + <seealso marker="ssl:ssl_distribution"> + Using SSL for Erlang Distribution</seealso> User's Guide + for details on how to setup a secure distributed node. + </item> <tag><c>inet6_tcp</c></tag> <item>TCP over IPv6</item> </taglist> @@ -490,6 +513,16 @@ exist between nodes running with flag <c><![CDATA[-sname]]></c> and those running with flag <c><![CDATA[-name]]></c>, as node names must be unique in distributed Erlang systems.</p> + <warning> + <p> + Starting a distributed node without also specifying + <seealso marker="#proto_dist"><c>-proto_dist inet_tls</c></seealso> + will expose the node to attacks that may give the attacker + complete access to the node and in extension the cluster. + When using un-secure distributed nodes, make sure that the + network is configured to keep potential attackers out. + </p> + </warning> </item> <tag><marker id="start_epmd"/><c>-start_epmd true | false</c></tag> <item> @@ -506,20 +539,6 @@ <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> start the Erlang runtime - system with SMP support enabled. This can fail if no runtime - system with SMP support is available. <c>-smp auto</c> starts - the Erlang runtime system with SMP support enabled if it is - available and more than one logical processor is detected. - <c>-smp disable</c> starts a runtime system without SMP support.</p> - <note> - <p>The runtime system with SMP support is not available on all - supported platforms. See also flag - <seealso marker="#+S"><c>+S</c></seealso>.</p> - </note> - </item> <tag><c><![CDATA[-version]]></c> (emulator flag)</tag> <item> <p>Makes the emulator print its version number. The same @@ -553,7 +572,7 @@ <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. Defaults to 10 if thread support is available.</p> + is 0-1024. Defaults to 1.</p> </item> <tag><c><![CDATA[+B [c | d | i]]]></c></tag> <item> @@ -612,14 +631,16 @@ of process heaps is destroyed by the crash dump generation.</p> <p>Option <c>+d</c> instructs the emulator to produce only a core dump and no crash dump if an internal error is detected.</p> - <p>Calling <seealso marker="erlang:halt/1"> + <p>Calling <seealso marker="erlang#halt/1"> <c>erlang:halt/1</c></seealso> with a string argument still produces a crash dump. On Unix systems, sending an emulator process a <c>SIGUSR1</c> signal also forces a crash dump.</p> </item> <tag><marker id="+e"/><c><![CDATA[+e Number]]></c></tag> <item> - <p>Sets the maximum number of ETS tables.</p> + <p>Sets the maximum number of ETS tables. This limit is + <seealso marker="stdlib:ets#max_ets_tables">partially obsolete</seealso>. + </p> </item> <tag><c><![CDATA[+ec]]></c></tag> <item> @@ -638,7 +659,7 @@ this value also applies to command-line parameters and environment variables (see section <seealso marker="stdlib:unicode_usage#unicode_in_environment_and_parameters"> - Unicode in Enviroment and Parameters</seealso> in the STDLIB + Unicode in Environment and Parameters</seealso> in the STDLIB User's Guide).</p> </item> <tag><c><![CDATA[+fnu[{w|i|e}]]]></c></tag> @@ -674,7 +695,7 @@ this value also applies to command-line parameters and environment variables (see section <seealso marker="stdlib:unicode_usage#unicode_in_environment_and_parameters"> - Unicode in Enviroment and Parameters</seealso> in the STDLIB + Unicode in Environment and Parameters</seealso> in the STDLIB User's Guide).</p> </item> <tag><c><![CDATA[+fna[{w|i|e}]]]></c></tag> @@ -695,7 +716,7 @@ this value also applies to command-line parameters and environment variables (see section <seealso marker="stdlib:unicode_usage#unicode_in_environment_and_parameters"> - Unicode in Enviroment and Parameters</seealso> in the STDLIB + Unicode in Environment and Parameters</seealso> in the STDLIB User's Guide).</p> </item> <tag><c><![CDATA[+hms Size]]></c></tag> @@ -744,13 +765,40 @@ <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> + <tag><marker id="+IOp"/><c>+IOp PollSets</c></tag> + <item> + <p>Sets the number of IO pollsets to use when polling for I/O. + This option is only used on platforms that support concurrent + updates of a pollset, otherwise the same number of pollsets + are used as IO poll threads. + The default is 1. + </p> + </item> + <tag><marker id="+IOt"/><c>+IOt PollThreads</c></tag> + <item> + <p>Sets the number of IO poll threads to use when polling for I/O. + The maximum number of poll threads allowed is 1024. The default is 1. + </p> + <p>A good way to check if more IO poll threads are needed is to use + <seealso marker="runtime_tools:msacc">microstate accounting</seealso> + and see what the load of the IO poll thread is. If it is high it could + be a good idea to add more threads.</p> + </item> + <tag><marker id="+IOPp"/><c>+IOPp PollSetsPercentage</c></tag> + <item> + <p>Similar to <seealso marker="#+IOp"><c>+IOp</c></seealso> but uses + percentages to set the number of IO pollsets to create, based on the + number of poll threads configured. If both <c>+IOPp</c> and <c>+IOp</c> + are used, <c>+IOPp</c> is ignored. + </p> + </item> + <tag><marker id="+IOPt"/><c>+IOPt PollThreadsPercentage</c></tag> <item> - <p>Enables or disables the kernel poll functionality if supported by - the emulator. Defaults to <c><![CDATA[false]]></c> (disabled). - If the emulator does not support kernel poll, and flag - <c><![CDATA[+K]]></c> is passed to the emulator, a warning is - issued at startup.</p> + <p>Similar to <seealso marker="#+IOt"><c>+IOt</c></seealso> but uses + percentages to set the number of IO poll threads to create, based on + the number of schedulers configured. If both <c>+IOPt</c> and + <c>+IOt</c> are used, <c>+IOPt</c> is ignored. + </p> </item> <tag><c><![CDATA[+l]]></c></tag> <item> @@ -870,7 +918,7 @@ <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 + to set online. The maximum for both values is 1024. If the Erlang runtime system is able to determine the number of logical processors configured and logical processors available, <c>Schedulers</c> defaults to logical processors @@ -888,8 +936,6 @@ <p>Specifying value <c>0</c> 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 does not have SMP support - enabled (see flag <seealso marker="#smp"><c>-smp</c></seealso>).</p> </item> <tag><marker id="+SP"/><c><![CDATA[+SP SchedulersPercentage:SchedulersOnlinePercentage]]></c></tag> @@ -897,8 +943,8 @@ <p>Similar to <seealso marker="#+S"><c>+S</c></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 > 0. For example, + based on logical processors available. + Specified values must be > 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. @@ -913,15 +959,13 @@ 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 does not have SMP support - enabled (see flag <seealso marker="#smp"><c>-smp</c></seealso>).</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 + CPU scheduler threads to set online. + The maximum for both values is 1024, and each value is further limited by the settings for normal schedulers:</p> <list type="bulleted"> <item>The number of dirty CPU scheduler threads created cannot exceed @@ -945,18 +989,14 @@ 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 does not have threading - support enabled. <em>This option is experimental</em> and - is supported only if the emulator was configured and built with - support for dirty schedulers enabled (it is disabled by default).</p> </item> <tag><marker id="+SDPcpu"/><c><![CDATA[+SDPcpu DirtyCPUSchedulersPercentage:DirtyCPUSchedulersOnlinePercentage]]></c></tag> <item> <p>Similar to <seealso marker="#+SDcpu"><c>+SDcpu</c></seealso> but uses percentages to set the number of dirty CPU scheduler threads to - create and the number of dirty CPU scheduler threads to set online - when threading support has been enabled. Specified values must be + create and the number of dirty CPU scheduler threads to set online. + Specified values must be > 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 @@ -973,15 +1013,11 @@ 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 does not have threading - support enabled. <em>This option is experimental</em> and - is supported only if the emulator was configured and built with - support for dirty schedulers enabled (it is 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. Valid range is 0-1024. By + <p>Sets the number of dirty I/O scheduler threads to create. + 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> @@ -991,10 +1027,6 @@ 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 does not have threading - support enabled. <em>This option is experimental</em> and - is supported only if the emulator was configured and built with - support for dirty schedulers enabled (it is disabled by default).</p> </item> <tag><c><![CDATA[+sFlag Value]]></c></tag> <item> @@ -1125,6 +1157,26 @@ without prior notice.</p> </note> </item> + <tag><marker id="+sbwtdcpu"/> + <c>+sbwtdcpu none|very_short|short|medium|long|very_long</c></tag> + <item> + <p>As <seealso marker="#+sbwt"><c>+sbwt</c></seealso> but affects + dirty CPU schedulers. Defaults to <c>short</c>.</p> + <note> + <p>This flag can be removed or changed at any time + without prior notice.</p> + </note> + </item> + <tag><marker id="+sbwtdio"/> + <c>+sbwtdio none|very_short|short|medium|long|very_long</c></tag> + <item> + <p>As <seealso marker="#+sbwt"><c>+sbwt</c></seealso> but affects + dirty IO schedulers. Defaults to <c>short</c>.</p> + <note> + <p>This flag can be removed or changed at any time + without prior notice.</p> + </note> + </item> <tag><marker id="+scl"/><c>+scl true|false</c></tag> <item> <p>Enables or disables scheduler compaction of load. By default @@ -1271,25 +1323,6 @@ <seealso marker="erlang#system_info_cpu_topology"> <c>erlang:system_info(cpu_topology)</c></seealso>.</p> </item> - <tag><marker id="+secio"/><c>+secio true|false</c></tag> - <item> - <p>Enables or disables eager check I/O scheduling. Defaults - to <c>true</c>. The default was changed from <c>false</c> - as from ERTS 7.0. The behavior 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 parameter name implies, - schedulers are more eager to check for I/O when - <c>true</c> is passed. This, however, also implies that - execution of outstanding I/O operation is not - 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 virtual machine.</p> - </item> <tag><marker id="+sfwi"/><c>+sfwi Interval</c></tag> <item> <p>Sets scheduler-forced wakeup interval. All run queues are @@ -1324,8 +1357,22 @@ <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 is - OS-dependent.</p> + Valid range is 20-8192 kilowords. The default suggested + stack size is 128 kilowords.</p> + </item> + <tag><marker id="dcpu_sched_thread_stack_size"/> + <c><![CDATA[+sssdcpu size]]></c></tag> + <item> + <p>Suggested stack size, in kilowords, for dirty CPU scheduler + threads. Valid range is 20-8192 kilowords. The default + suggested stack size is 40 kilowords.</p> + </item> + <tag><marker id="dio_sched_thread_stack_size"/> + <c><![CDATA[+sssdio size]]></c></tag> + <item> + <p>Suggested stack size, in kilowords, for dirty IO scheduler + threads. Valid range is 20-8192 kilowords. The default + suggested stack size is 40 kilowords.</p> </item> <tag><marker id="+stbt"/><c>+stbt BindType</c></tag> <item> @@ -1395,6 +1442,26 @@ notice.</p> </note> </item> + <tag><marker id="+swtdcpu"/> + <c>+swtdcpu very_low|low|medium|high|very_high</c></tag> + <item> + <p>As <seealso marker="#+swt"><c>+swt</c></seealso> but + affects dirty CPU schedulers. Defaults to <c>medium</c>.</p> + <note> + <p>This flag can be removed or changed at any time + without prior notice.</p> + </note> + </item> + <tag><marker id="+swtdio"/> + <c>+swtdio very_low|low|medium|high|very_high</c></tag> + <item> + <p>As <seealso marker="#+swt"><c>+swt</c></seealso> but affects + dirty IO schedulers. Defaults to <c>medium</c>.</p> + <note> + <p>This flag can be removed or changed at any time + without prior notice.</p> + </note> + </item> </taglist> </item> <tag><marker id="+t"/><c><![CDATA[+t size]]></c></tag> @@ -1513,32 +1580,27 @@ <item> <p><em>Unix systems</em>: This variable gives the number of seconds that the emulator is allowed to spend writing a crash dump. When the - given number of seconds have elapsed, the emulator is terminated by a - <c>SIGALRM</c> signal.</p> - <p>If the variable is <em>not</em> set or set to <c>0</c> seconds - (<c><![CDATA[ERL_CRASH_DUMP_SECONDS=0]]></c>), the runtime system does - not even attempt to write the crash dump file. It only terminates.</p> - <p>If the variable is set to negative value, such as - <c><![CDATA[ERL_CRASH_DUMP_SECONDS=-1]]></c>, the runtime system - waits indefinitely for the crash dump file to be written.</p> - <p>This variable is used with <seealso marker="kernel:heart"> - <c>heart(3)</c></seealso> if <c>heart</c> is running:</p> + given number of seconds have elapsed, the emulator is terminated.</p> <taglist> <tag><c><![CDATA[ERL_CRASH_DUMP_SECONDS=0]]></c></tag> - <item>Suppresses the writing a crash dump file entirely, thus - rebooting the runtime system immediately. This is the same as not - setting the environment variable. + <item>If the variable is set to <c>0</c> seconds, the runtime system does + not even attempt to write the crash dump file. It only terminates. + This is the default if option <c>-heart</c> is passed to <c>erl</c> + and <c>ERL_CRASH_DUMP_SECONDS</c> is not set. + </item> + <tag><c><![CDATA[ERL_CRASH_DUMP_SECONDS=S]]></c></tag> + <item>If the variable is set to a positive value <c>S</c>, + wait for <c>S</c> seconds to complete the crash dump file and + then terminates the runtime system with a <c>SIGALRM</c> signal. </item> <tag><c><![CDATA[ERL_CRASH_DUMP_SECONDS=-1]]></c></tag> - <item>Setting the environment variable to a negative value causes the - termination of the runtime system to wait until the crash dump file - has been completly written. - </item> - <tag><c><![CDATA[ERL_CRASH_DUMP_SECONDS=S]]></c></tag> - <item>Waits for <c>S</c> seconds to complete the crash dump file and - then terminates the runtime system. + <item>A negative value causes the termination of the runtime system + to wait indefinitely until the crash dump file has been completly + written. This is the default if option <c>-heart</c> is <em>not</em> + passed to <c>erl</c> and <c>ERL_CRASH_DUMP_SECONDS</c> is not set. </item> </taglist> + <p>See also <seealso marker="kernel:heart"><c>heart(3)</c></seealso>.</p> </item> <tag><c><![CDATA[ERL_CRASH_DUMP_BYTES]]></c></tag> <item> @@ -1622,9 +1684,7 @@ <tag>The <c>.erlang</c> startup file</tag> <item> <p>When Erlang/OTP is started, the system searches for a file named - <c>.erlang</c> in the directory where Erlang/OTP is started. If not - found, the user's home directory is searched for an <c>.erlang</c> - file.</p> + <c>.erlang</c> in the user's home directory.</p> <p>If an <c>.erlang</c> file is found, it is assumed to contain valid Erlang expressions. These expressions are evaluated as if they were input to the shell.</p> @@ -1676,4 +1736,3 @@ code:load_abs("..../user_default"). ]]></code> <seealso marker="tools:make"><c>make(3)</c></seealso></p> </section> </comref> - diff --git a/erts/doc/src/erl_dist_protocol.xml b/erts/doc/src/erl_dist_protocol.xml index ee74983730..c90c8f9521 100644 --- a/erts/doc/src/erl_dist_protocol.xml +++ b/erts/doc/src/erl_dist_protocol.xml @@ -5,7 +5,7 @@ <header> <copyright> <year>2007</year> - <year>2016</year> + <year>2018</year> <holder>Ericsson AB, All Rights Reserved</holder> </copyright> <legalnotice> @@ -70,6 +70,17 @@ <p>The integers in all multibyte fields are in big-endian order.</p> + <warning> + <p> + The Erlang Distribution protocol is not by itself secure and does not + aim to be so. In order to get secure distribution the distributed nodes + should be configured to use distribution over tls. + See the <seealso marker="ssl:ssl_distribution"> + Using SSL for Erlang Distribution</seealso> User's Guide + for details on how to setup a secure distributed node. + </p> + </warning> + <section> <title>EPMD Protocol</title> <p>The requests served by the EPMD are summarized in the following @@ -818,7 +829,30 @@ DiB == gen_digest(ChA, ICA)? <item> <p>The node understand UTF-8 encoded atoms.</p> </item> + <tag><c>-define(DFLAG_MAP_TAG, 16#20000).</c></tag> + <item> + <p>The node understand the map tag.</p> + </item> + <tag><c>-define(DFLAG_BIG_CREATION, 16#40000).</c></tag> + <item> + <p>The node understand big node creation.</p> + </item> + <tag><c>-define(DFLAG_SEND_SENDER, 16#80000).</c></tag> + <item> + <p> + Use the <c>SEND_SENDER</c> + <seealso marker="#control_message">control message</seealso> + instead of the <c>SEND</c> control message and use the + <c>SEND_SENDER_TT</c> control message instead + of the <c>SEND_TT</c> control message. + </p> + </item> </taglist> + <p> + There is also function <c>dist_util:strict_order_flags/0</c> + returning all flags (bitwise or:ed together) corresponding to features + that require strict ordering of data over distribution channels. + </p> </section> </section> @@ -911,6 +945,7 @@ DiB == gen_digest(ChA, ICA)? </item> </taglist> + <marker id="control_message"/> <p>The <c>ControlMessage</c> is a tuple, where the first element indicates which distributed operation it encodes:</p> @@ -1017,4 +1052,49 @@ DiB == gen_digest(ChA, ICA)? </item> </taglist> </section> + + <section> + <title>New Ctrlmessages for Erlang/OTP 21</title> + <taglist> + <tag><c>SEND_SENDER</c></tag> + <item> + <p><c>{22, FromPid, ToPid}</c></p> + <p>Followed by <c>Message</c>.</p> + <p> + This control messages replace the <c>SEND</c> control + message and will be sent when the distribution flag + <seealso marker="erl_dist_protocol#dflags"><c>DFLAG_SEND_SENDER</c></seealso> + has been negotiated in the connection setup handshake. + </p> + <note><p> + Messages encoded before the connection has + been set up may still use the <c>SEND</c> control + message. However, once a <c>SEND_SENDER</c> or <c>SEND_SENDER_TT</c> + control message has been sent, no more <c>SEND</c> + control messages will be sent in the same direction + on the connection. + </p></note> + </item> + <tag><c>SEND_SENDER_TT</c></tag> + <item> + <p><c>{23, FromPid, ToPid, TraceToken}</c></p> + <p>Followed by <c>Message</c>.</p> + <p> + This control messages replace the <c>SEND_TT</c> control + message and will be sent when the distribution flag + <seealso marker="erl_dist_protocol#dflags"><c>DFLAG_SEND_SENDER</c></seealso> + has been negotiated in the connection setup handshake. + </p> + <note><p> + Messages encoded before the connection has + been set up may still use the <c>SEND_TT</c> control + message. However, once a <c>SEND_SENDER</c> or <c>SEND_SENDER_TT</c> + control message has been sent, no more <c>SEND_TT</c> + control messages will be sent in the same direction + on the connection. + </p></note> + </item> + </taglist> + </section> + </chapter> diff --git a/erts/doc/src/erl_driver.xml b/erts/doc/src/erl_driver.xml index 5705100ab2..58678f2393 100644 --- a/erts/doc/src/erl_driver.xml +++ b/erts/doc/src/erl_driver.xml @@ -4,7 +4,7 @@ <cref> <header> <copyright> - <year>2001</year><year>2017</year> + <year>2001</year><year>2018</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -157,7 +157,7 @@ </note> <p>Most functions in this API are <em>not</em> thread-safe, that is, - they <em>cannot</em> be called from any thread. Functions + they <em>cannot</em> be called from arbitrary threads. Functions that are not documented as thread-safe can only be called from driver callbacks or function calls descending from a driver callback call. Notice that driver callbacks can be called from @@ -429,7 +429,7 @@ <taglist> <tag>Return types for driver callbacks</tag> <item> - <p>Rrewrite driver callback + <p>Rewrite driver callback <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 @@ -841,7 +841,7 @@ int suggested_stack_size;</code> <p>Thread options structure passed to <seealso marker="#erl_drv_thread_create"> <c>erl_drv_thread_create</c></seealso>. - The following fields exists:</p> + The following field exists:</p> <taglist> <tag><c>suggested_stack_size</c></tag> <item>A suggestion, in kilowords, on how large a stack to use. @@ -944,7 +944,7 @@ int suggested_stack_size;</code> <funcs> <func> - <name><ret>void</ret><nametext>add_driver_entry(ErlDrvEntry + <name since=""><ret>void</ret><nametext>add_driver_entry(ErlDrvEntry *de)</nametext></name> <fsummary>Add a driver entry.</fsummary> <desc> @@ -968,7 +968,7 @@ int suggested_stack_size;</code> </func> <func> - <name><ret>void *</ret> + <name since=""><ret>void *</ret> <nametext>driver_alloc(ErlDrvSizeT size)</nametext></name> <fsummary>Allocate memory.</fsummary> <desc> @@ -985,7 +985,7 @@ int suggested_stack_size;</code> </func> <func> - <name><ret>ErlDrvBinary *</ret> + <name since=""><ret>ErlDrvBinary *</ret> <nametext>driver_alloc_binary(ErlDrvSizeT size)</nametext></name> <fsummary>Allocate a driver binary.</fsummary> <desc> @@ -1008,7 +1008,7 @@ int suggested_stack_size;</code> </func> <func> - <name><ret>long</ret><nametext>driver_async(ErlDrvPort port, unsigned + <name since=""><ret>long</ret><nametext>driver_async(ErlDrvPort port, unsigned int* key, void (*async_invoke)(void*), void* async_data, void (*async_free)(void*))</nametext></name> <fsummary>Perform an asynchronous call within a driver.</fsummary> @@ -1076,7 +1076,7 @@ r = driver_async(myPort, &myKey, myData, myFunc); ]]></code> </func> <func> - <name><ret>unsigned int</ret><nametext>driver_async_port_key(ErlDrvPort + <name since="OTP R16B02"><ret>unsigned int</ret><nametext>driver_async_port_key(ErlDrvPort port)</nametext></name> <fsummary>Calculate an async key from an ErlDrvPort.</fsummary> <desc> @@ -1096,7 +1096,7 @@ r = driver_async(myPort, &myKey, myData, myFunc); ]]></code> </func> <func> - <name><ret>long</ret> + <name since=""><ret>long</ret> <nametext>driver_binary_dec_refc(ErlDrvBinary *bin)</nametext></name> <fsummary>Decrement the reference count of a driver binary.</fsummary> <desc> @@ -1117,7 +1117,7 @@ r = driver_async(myPort, &myKey, myData, myFunc); ]]></code> </func> <func> - <name><ret>long</ret> + <name since=""><ret>long</ret> <nametext>driver_binary_get_refc(ErlDrvBinary *bin)</nametext></name> <fsummary>Get the reference count of a driver binary.</fsummary> <desc> @@ -1128,7 +1128,7 @@ r = driver_async(myPort, &myKey, myData, myFunc); ]]></code> </func> <func> - <name><ret>long</ret> + <name since=""><ret>long</ret> <nametext>driver_binary_inc_refc(ErlDrvBinary *bin)</nametext></name> <fsummary>Increment the reference count of a driver binary.</fsummary> <desc> @@ -1140,7 +1140,7 @@ r = driver_async(myPort, &myKey, myData, myFunc); ]]></code> </func> <func> - <name><ret>ErlDrvTermData</ret><nametext>driver_caller(ErlDrvPort + <name since=""><ret>ErlDrvTermData</ret><nametext>driver_caller(ErlDrvPort port)</nametext></name> <fsummary>Return the process making the driver call.</fsummary> <desc> @@ -1183,7 +1183,7 @@ r = driver_async(myPort, &myKey, myData, myFunc); ]]></code> </func> <func> - <name><ret>int</ret> + <name since=""><ret>int</ret> <nametext>driver_cancel_timer(ErlDrvPort port)</nametext></name> <fsummary>Cancel a previously set timer.</fsummary> <desc> @@ -1196,7 +1196,7 @@ r = driver_async(myPort, &myKey, myData, myFunc); ]]></code> </func> <func> - <name><ret>int</ret><nametext>driver_compare_monitors(const ErlDrvMonitor + <name since=""><ret>int</ret><nametext>driver_compare_monitors(const ErlDrvMonitor *monitor1, const ErlDrvMonitor *monitor2)</nametext></name> <fsummary>Compare two monitors.</fsummary> <desc> @@ -1211,7 +1211,7 @@ r = driver_async(myPort, &myKey, myData, myFunc); ]]></code> </func> <func> - <name><ret>ErlDrvTermData</ret><nametext>driver_connected(ErlDrvPort + <name since=""><ret>ErlDrvTermData</ret><nametext>driver_connected(ErlDrvPort port)</nametext></name> <fsummary>Return the port owner process.</fsummary> <desc> @@ -1223,7 +1223,7 @@ r = driver_async(myPort, &myKey, myData, myFunc); ]]></code> </func> <func> - <name><ret>ErlDrvPort</ret><nametext>driver_create_port(ErlDrvPort port, + <name since=""><ret>ErlDrvPort</ret><nametext>driver_create_port(ErlDrvPort port, ErlDrvTermData owner_pid, char* name, ErlDrvData drv_data)</nametext></name> <fsummary>Create a new port (driver instance).</fsummary> @@ -1269,7 +1269,7 @@ r = driver_async(myPort, &myKey, myData, myFunc); ]]></code> </func> <func> - <name><ret>int</ret><nametext>driver_demonitor_process(ErlDrvPort port, + <name since=""><ret>int</ret><nametext>driver_demonitor_process(ErlDrvPort port, const ErlDrvMonitor *monitor)</nametext></name> <fsummary>Stop monitoring a process from a driver.</fsummary> <desc> @@ -1281,7 +1281,7 @@ r = driver_async(myPort, &myKey, myData, myFunc); ]]></code> </func> <func> - <name><ret>ErlDrvSizeT</ret><nametext>driver_deq(ErlDrvPort port, + <name since=""><ret>ErlDrvSizeT</ret><nametext>driver_deq(ErlDrvPort port, ErlDrvSizeT size)</nametext></name> <fsummary>Dequeue data from the head of the driver queue.</fsummary> <desc> @@ -1299,7 +1299,7 @@ r = driver_async(myPort, &myKey, myData, myFunc); ]]></code> </func> <func> - <name><ret>int</ret><nametext>driver_enq(ErlDrvPort port, char* buf, + <name since=""><ret>int</ret><nametext>driver_enq(ErlDrvPort port, char* buf, ErlDrvSizeT len)</nametext></name> <fsummary>Enqueue data in the driver queue.</fsummary> <desc> @@ -1325,7 +1325,7 @@ r = driver_async(myPort, &myKey, myData, myFunc); ]]></code> </func> <func> - <name><ret>int</ret><nametext>driver_enq_bin(ErlDrvPort port, + <name since=""><ret>int</ret><nametext>driver_enq_bin(ErlDrvPort port, ErlDrvBinary *bin, ErlDrvSizeT offset, ErlDrvSizeT len)</nametext> </name> <fsummary>Enqueue binary in the driver queue.</fsummary> @@ -1346,7 +1346,7 @@ r = driver_async(myPort, &myKey, myData, myFunc); ]]></code> </func> <func> - <name><ret>int</ret><nametext>driver_enqv(ErlDrvPort port, ErlIOVec *ev, + <name since=""><ret>int</ret><nametext>driver_enqv(ErlDrvPort port, ErlIOVec *ev, ErlDrvSizeT skip)</nametext></name> <fsummary>Enqueue vector in the driver queue.</fsummary> <desc> @@ -1365,11 +1365,11 @@ r = driver_async(myPort, &myKey, myData, myFunc); ]]></code> </func> <func> - <name><ret>int</ret><nametext>driver_failure(ErlDrvPort port, int + <name since=""><ret>int</ret><nametext>driver_failure(ErlDrvPort port, int error)</nametext></name> - <name><ret>int</ret><nametext>driver_failure_atom(ErlDrvPort port, char + <name since=""><ret>int</ret><nametext>driver_failure_atom(ErlDrvPort port, char *string)</nametext></name> - <name><ret>int</ret><nametext>driver_failure_posix(ErlDrvPort port, int + <name since=""><ret>int</ret><nametext>driver_failure_posix(ErlDrvPort port, int error)</nametext></name> <fsummary>Fail with error.</fsummary> <desc> @@ -1393,7 +1393,7 @@ r = driver_async(myPort, &myKey, myData, myFunc); ]]></code> </func> <func> - <name><ret>int</ret><nametext>driver_failure_eof(ErlDrvPort + <name since=""><ret>int</ret><nametext>driver_failure_eof(ErlDrvPort port)</nametext></name> <fsummary>Fail with EOF.</fsummary> <desc> @@ -1408,7 +1408,7 @@ r = driver_async(myPort, &myKey, myData, myFunc); ]]></code> </func> <func> - <name><ret>void</ret><nametext>driver_free(void *ptr)</nametext></name> + <name since=""><ret>void</ret><nametext>driver_free(void *ptr)</nametext></name> <fsummary>Free an allocated memory block.</fsummary> <desc> <marker id="driver_free"></marker> @@ -1422,7 +1422,7 @@ r = driver_async(myPort, &myKey, myData, myFunc); ]]></code> </func> <func> - <name><ret>void</ret> + <name since=""><ret>void</ret> <nametext>driver_free_binary(ErlDrvBinary *bin)</nametext></name> <fsummary>Free a driver binary.</fsummary> <desc> @@ -1436,7 +1436,7 @@ r = driver_async(myPort, &myKey, myData, myFunc); ]]></code> </func> <func> - <name><ret>ErlDrvTermData</ret> + <name since=""><ret>ErlDrvTermData</ret> <nametext>driver_get_monitored_process(ErlDrvPort port, const ErlDrvMonitor *monitor)</nametext></name> <fsummary>Retrieve the process ID from a monitor.</fsummary> @@ -1452,7 +1452,7 @@ r = driver_async(myPort, &myKey, myData, myFunc); ]]></code> </func> <func> - <name><ret>int</ret> + <name since=""><ret>int</ret> <nametext>driver_get_now(ErlDrvNowData *now)</nametext></name> <fsummary>Read a system time stamp.</fsummary> <desc> @@ -1473,7 +1473,7 @@ r = driver_async(myPort, &myKey, myData, myFunc); ]]></code> </func> <func> - <name><ret>int</ret><nametext>driver_lock_driver(ErlDrvPort + <name since=""><ret>int</ret><nametext>driver_lock_driver(ErlDrvPort port)</nametext></name> <fsummary>Ensure the driver is never unloaded.</fsummary> <desc> @@ -1486,7 +1486,7 @@ r = driver_async(myPort, &myKey, myData, myFunc); ]]></code> </func> <func> - <name><ret>ErlDrvTermData</ret><nametext>driver_mk_atom(char* + <name since=""><ret>ErlDrvTermData</ret><nametext>driver_mk_atom(char* string)</nametext></name> <fsummary>Make an atom from a name.</fsummary> <desc> @@ -1501,7 +1501,7 @@ r = driver_async(myPort, &myKey, myData, myFunc); ]]></code> </func> <func> - <name><ret>ErlDrvTermData</ret><nametext>driver_mk_port(ErlDrvPort + <name since=""><ret>ErlDrvTermData</ret><nametext>driver_mk_port(ErlDrvPort port)</nametext></name> <fsummary>Make an Erlang term port from a port.</fsummary> <desc> @@ -1517,7 +1517,7 @@ r = driver_async(myPort, &myKey, myData, myFunc); ]]></code> </func> <func> - <name><ret>int</ret><nametext>driver_monitor_process(ErlDrvPort port, + <name since=""><ret>int</ret><nametext>driver_monitor_process(ErlDrvPort port, ErlDrvTermData process, ErlDrvMonitor *monitor)</nametext></name> <fsummary>Monitor a process from a driver.</fsummary> <desc> @@ -1540,7 +1540,7 @@ r = driver_async(myPort, &myKey, myData, myFunc); ]]></code> </func> <func> - <name><ret>int</ret><nametext>driver_output(ErlDrvPort port, char *buf, + <name since=""><ret>int</ret><nametext>driver_output(ErlDrvPort port, char *buf, ErlDrvSizeT len)</nametext></name> <fsummary>Send data from driver to port owner.</fsummary> <desc> @@ -1560,7 +1560,7 @@ r = driver_async(myPort, &myKey, myData, myFunc); ]]></code> </func> <func> - <name><ret>int</ret><nametext>driver_output_binary(ErlDrvPort port, char + <name since=""><ret>int</ret><nametext>driver_output_binary(ErlDrvPort port, char *hbuf, ErlDrvSizeT hlen, ErlDrvBinary* bin, ErlDrvSizeT offset, ErlDrvSizeT len)</nametext></name> <fsummary>Send data from a driver binary to port owner.</fsummary> @@ -1589,7 +1589,7 @@ r = driver_async(myPort, &myKey, myData, myFunc); ]]></code> </func> <func> - <name><ret>int</ret><nametext>driver_output_term(ErlDrvPort port, + <name since=""><ret>int</ret><nametext>driver_output_term(ErlDrvPort port, ErlDrvTermData* term, int n)</nametext></name> <fsummary>Send term data from driver to port owner.</fsummary> <desc> @@ -1608,7 +1608,7 @@ r = driver_async(myPort, &myKey, myData, myFunc); ]]></code> </func> <func> - <name><ret>int</ret><nametext>driver_output2(ErlDrvPort port, char *hbuf, + <name since=""><ret>int</ret><nametext>driver_output2(ErlDrvPort port, char *hbuf, ErlDrvSizeT hlen, char *buf, ErlDrvSizeT len)</nametext></name> <fsummary>Send data and binary data to port owner.</fsummary> <desc> @@ -1625,7 +1625,7 @@ r = driver_async(myPort, &myKey, myData, myFunc); ]]></code> </func> <func> - <name><ret>int</ret><nametext>driver_outputv(ErlDrvPort port, char* hbuf, + <name since=""><ret>int</ret><nametext>driver_outputv(ErlDrvPort port, char* hbuf, ErlDrvSizeT hlen, ErlIOVec *ev, ErlDrvSizeT skip)</nametext></name> <fsummary>Send vectorized data to port owner.</fsummary> <desc> @@ -1654,7 +1654,7 @@ r = driver_async(myPort, &myKey, myData, myFunc); ]]></code> </func> <func> - <name><ret>ErlDrvPDL</ret> + <name since=""><ret>ErlDrvPDL</ret> <nametext>driver_pdl_create(ErlDrvPort port)</nametext></name> <fsummary>Create a port data lock.</fsummary> <desc> @@ -1672,7 +1672,7 @@ r = driver_async(myPort, &myKey, myData, myFunc); ]]></code> </func> <func> - <name><ret>long</ret><nametext>driver_pdl_dec_refc(ErlDrvPDL + <name since=""><ret>long</ret><nametext>driver_pdl_dec_refc(ErlDrvPDL pdl)</nametext></name> <fsummary></fsummary> <desc> @@ -1686,7 +1686,7 @@ r = driver_async(myPort, &myKey, myData, myFunc); ]]></code> </func> <func> - <name><ret>long</ret> + <name since=""><ret>long</ret> <nametext>driver_pdl_get_refc(ErlDrvPDL pdl)</nametext></name> <fsummary></fsummary> <desc> @@ -1698,7 +1698,7 @@ r = driver_async(myPort, &myKey, myData, myFunc); ]]></code> </func> <func> - <name><ret>long</ret> + <name since=""><ret>long</ret> <nametext>driver_pdl_inc_refc(ErlDrvPDL pdl)</nametext></name> <fsummary></fsummary> <desc> @@ -1712,7 +1712,7 @@ r = driver_async(myPort, &myKey, myData, myFunc); ]]></code> </func> <func> - <name><ret>void</ret> + <name since=""><ret>void</ret> <nametext>driver_pdl_lock(ErlDrvPDL pdl)</nametext></name> <fsummary>Lock port data lock.</fsummary> <desc> @@ -1723,7 +1723,7 @@ r = driver_async(myPort, &myKey, myData, myFunc); ]]></code> </func> <func> - <name><ret>void</ret> + <name since=""><ret>void</ret> <nametext>driver_pdl_unlock(ErlDrvPDL pdl)</nametext></name> <fsummary>Unlock port data lock.</fsummary> <desc> @@ -1734,7 +1734,7 @@ r = driver_async(myPort, &myKey, myData, myFunc); ]]></code> </func> <func> - <name><ret>SysIOVec *</ret><nametext>driver_peekq(ErlDrvPort port, int + <name since=""><ret>SysIOVec *</ret><nametext>driver_peekq(ErlDrvPort port, int *vlen)</nametext></name> <fsummary>Get the driver queue as a vector.</fsummary> <desc> @@ -1755,7 +1755,7 @@ r = driver_async(myPort, &myKey, myData, myFunc); ]]></code> </func> <func> - <name><ret>ErlDrvSizeT</ret><nametext>driver_peekqv(ErlDrvPort port, + <name since="OTP R15B"><ret>ErlDrvSizeT</ret><nametext>driver_peekqv(ErlDrvPort port, ErlIOVec *ev)</nametext></name> <fsummary>Get the driver queue as an I/O vector.</fsummary> <desc> @@ -1775,7 +1775,7 @@ r = driver_async(myPort, &myKey, myData, myFunc); ]]></code> </func> <func> - <name><ret>int</ret><nametext>driver_pushq(ErlDrvPort port, char* buf, + <name since=""><ret>int</ret><nametext>driver_pushq(ErlDrvPort port, char* buf, ErlDrvSizeT len)</nametext></name> <fsummary>Push data at the head of the driver queue.</fsummary> <desc> @@ -1792,7 +1792,7 @@ r = driver_async(myPort, &myKey, myData, myFunc); ]]></code> </func> <func> - <name><ret>int</ret><nametext>driver_pushq_bin(ErlDrvPort port, + <name since=""><ret>int</ret><nametext>driver_pushq_bin(ErlDrvPort port, ErlDrvBinary *bin, ErlDrvSizeT offset, ErlDrvSizeT len)</nametext> </name> <fsummary>Push binary at the head of the driver queue.</fsummary> @@ -1812,7 +1812,7 @@ r = driver_async(myPort, &myKey, myData, myFunc); ]]></code> </func> <func> - <name><ret>int</ret><nametext>driver_pushqv(ErlDrvPort port, ErlIOVec + <name since=""><ret>int</ret><nametext>driver_pushqv(ErlDrvPort port, ErlIOVec *ev, ErlDrvSizeT skip)</nametext></name> <fsummary>Push vector at the head of the driver queue.</fsummary> <desc> @@ -1831,7 +1831,7 @@ r = driver_async(myPort, &myKey, myData, myFunc); ]]></code> </func> <func> - <name><ret>int</ret><nametext>driver_read_timer(ErlDrvPort port, unsigned + <name since=""><ret>int</ret><nametext>driver_read_timer(ErlDrvPort port, unsigned long *time_left)</nametext></name> <fsummary>Read the time left before time-out.</fsummary> <desc> @@ -1844,7 +1844,7 @@ r = driver_async(myPort, &myKey, myData, myFunc); ]]></code> </func> <func> - <name><ret>void *</ret> + <name since=""><ret>void *</ret> <nametext>driver_realloc(void *ptr, ErlDrvSizeT size)</nametext></name> <fsummary>Resize an allocated memory block.</fsummary> <desc> @@ -1859,7 +1859,7 @@ r = driver_async(myPort, &myKey, myData, myFunc); ]]></code> </func> <func> - <name><ret>ErlDrvBinary *</ret> + <name since=""><ret>ErlDrvBinary *</ret> <nametext>driver_realloc_binary(ErlDrvBinary *bin, ErlDrvSizeT size) </nametext></name> <fsummary>Resize a driver binary.</fsummary> @@ -1873,7 +1873,7 @@ r = driver_async(myPort, &myKey, myData, myFunc); ]]></code> </func> <func> - <name><ret>int</ret><nametext>driver_select(ErlDrvPort port, ErlDrvEvent + <name since=""><ret>int</ret><nametext>driver_select(ErlDrvPort port, ErlDrvEvent event, int mode, int on)</nametext></name> <fsummary>Provides an event for having the emulator call the driver. </fsummary> @@ -1932,7 +1932,7 @@ r = driver_async(myPort, &myKey, myData, myFunc); ]]></code> </func> <func> - <name><ret>int</ret><nametext>driver_send_term(ErlDrvPort port, + <name since=""><ret>int</ret><nametext>driver_send_term(ErlDrvPort port, ErlDrvTermData receiver, ErlDrvTermData* term, int n)</nametext></name> <fsummary>Send term data to other process than port owner process. </fsummary> @@ -1958,7 +1958,7 @@ r = driver_async(myPort, &myKey, myData, myFunc); ]]></code> </func> <func> - <name><ret>int</ret><nametext>driver_set_timer(ErlDrvPort port, unsigned + <name since=""><ret>int</ret><nametext>driver_set_timer(ErlDrvPort port, unsigned long time)</nametext></name> <fsummary>Set a timer to call the driver.</fsummary> <desc> @@ -1977,7 +1977,7 @@ r = driver_async(myPort, &myKey, myData, myFunc); ]]></code> </func> <func> - <name><ret>ErlDrvSizeT</ret> + <name since=""><ret>ErlDrvSizeT</ret> <nametext>driver_sizeq(ErlDrvPort port)</nametext></name> <fsummary>Return the size of the driver queue.</fsummary> <desc> @@ -1991,7 +1991,7 @@ r = driver_async(myPort, &myKey, myData, myFunc); ]]></code> </func> <func> - <name><ret>void</ret><nametext>driver_system_info(ErlDrvSysInfo + <name since=""><ret>void</ret><nametext>driver_system_info(ErlDrvSysInfo *sys_info_ptr, size_t size)</nametext></name> <fsummary>Get information about the Erlang runtime system.</fsummary> <desc> @@ -2008,7 +2008,7 @@ r = driver_async(myPort, &myKey, myData, myFunc); ]]></code> </func> <func> - <name><ret>ErlDrvSizeT</ret><nametext>driver_vec_to_buf(ErlIOVec *ev, + <name since=""><ret>ErlDrvSizeT</ret><nametext>driver_vec_to_buf(ErlIOVec *ev, char *buf, ErlDrvSizeT len)</nametext></name> <fsummary>Collect data segments into a buffer.</fsummary> <desc> @@ -2029,7 +2029,7 @@ r = driver_async(myPort, &myKey, myData, myFunc); ]]></code> </func> <func> - <name><ret>void</ret><nametext>erl_drv_busy_msgq_limits(ErlDrvPort port, + <name since="OTP R16B"><ret>void</ret><nametext>erl_drv_busy_msgq_limits(ErlDrvPort port, ErlDrvSizeT *low, ErlDrvSizeT *high)</nametext></name> <fsummary>Set and get limits for busy port message queue.</fsummary> <desc> @@ -2083,7 +2083,7 @@ r = driver_async(myPort, &myKey, myData, myFunc); ]]></code> </func> <func> - <name><ret>void</ret><nametext>erl_drv_cond_broadcast(ErlDrvCond + <name since=""><ret>void</ret><nametext>erl_drv_cond_broadcast(ErlDrvCond *cnd)</nametext></name> <fsummary>Broadcast on a condition variable.</fsummary> <desc> @@ -2097,7 +2097,7 @@ r = driver_async(myPort, &myKey, myData, myFunc); ]]></code> </func> <func> - <name><ret>ErlDrvCond *</ret><nametext>erl_drv_cond_create(char + <name since=""><ret>ErlDrvCond *</ret><nametext>erl_drv_cond_create(char *name)</nametext></name> <fsummary>Create a condition variable.</fsummary> <desc> @@ -2114,7 +2114,7 @@ r = driver_async(myPort, &myKey, myData, myFunc); ]]></code> </func> <func> - <name><ret>void</ret><nametext>erl_drv_cond_destroy(ErlDrvCond + <name since=""><ret>void</ret><nametext>erl_drv_cond_destroy(ErlDrvCond *cnd)</nametext></name> <fsummary>Destroy a condition variable.</fsummary> <desc> @@ -2128,7 +2128,7 @@ r = driver_async(myPort, &myKey, myData, myFunc); ]]></code> </func> <func> - <name><ret>char *</ret><nametext>erl_drv_cond_name(ErlDrvCond + <name since="OTP R16B02"><ret>char *</ret><nametext>erl_drv_cond_name(ErlDrvCond *cnd)</nametext></name> <fsummary>Get name of driver mutex.</fsummary> <desc> @@ -2142,7 +2142,7 @@ r = driver_async(myPort, &myKey, myData, myFunc); ]]></code> </func> <func> - <name><ret>void</ret><nametext>erl_drv_cond_signal(ErlDrvCond + <name since=""><ret>void</ret><nametext>erl_drv_cond_signal(ErlDrvCond *cnd)</nametext></name> <fsummary>Signal on a condition variable.</fsummary> <desc> @@ -2156,7 +2156,7 @@ r = driver_async(myPort, &myKey, myData, myFunc); ]]></code> </func> <func> - <name><ret>void</ret><nametext>erl_drv_cond_wait(ErlDrvCond *cnd, + <name since=""><ret>void</ret><nametext>erl_drv_cond_wait(ErlDrvCond *cnd, ErlDrvMutex *mtx)</nametext></name> <fsummary>Wait on a condition variable.</fsummary> <desc> @@ -2185,7 +2185,7 @@ r = driver_async(myPort, &myKey, myData, myFunc); ]]></code> </func> <func> - <name><ret>int</ret><nametext>erl_drv_consume_timeslice(ErlDrvPort port, + <name since="OTP R16B"><ret>int</ret><nametext>erl_drv_consume_timeslice(ErlDrvPort port, int percent)</nametext></name> <fsummary>Give the runtime system a hint about how much CPU time the current driver callback call has consumed.</fsummary> @@ -2228,7 +2228,7 @@ r = driver_async(myPort, &myKey, myData, myFunc); ]]></code> </func> <func> - <name><ret>ErlDrvTime</ret><nametext>erl_drv_convert_time_unit(ErlDrvTime + <name since="OTP 18.3"><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> @@ -2254,7 +2254,7 @@ r = driver_async(myPort, &myKey, myData, myFunc); ]]></code> </func> <func> - <name><ret>int</ret><nametext>erl_drv_equal_tids(ErlDrvTid tid1, + <name since=""><ret>int</ret><nametext>erl_drv_equal_tids(ErlDrvTid tid1, ErlDrvTid tid2)</nametext></name> <fsummary>Compare thread identifiers for equality.</fsummary> <desc> @@ -2276,7 +2276,7 @@ r = driver_async(myPort, &myKey, myData, myFunc); ]]></code> </func> <func> - <name><ret>int</ret><nametext>erl_drv_getenv(const char *key, char + <name since=""><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> @@ -2304,15 +2304,20 @@ r = driver_async(myPort, &myKey, myData, myFunc); ]]></code> buffer is too small, a value > <c>0</c> is returned and <c>*value_size</c> has been set to the buffer size needed.</p> <warning> - <p>Do <em>not</em> use libc's <c>getenv</c> or similar C library - interfaces from a driver.</p> + <p>This function reads the emulated environment used by + <seealso marker="os:getenv/1"><c>os:getenv/1</c></seealso> and not + the environment used by libc's <c>getenv(3)</c> or similar. Drivers + that <em>require</em> that these are in sync will need to do so + themselves, but keep in mind that they are segregated for a reason; + <c>getenv(3)</c> and its friends are <em>not thread-safe</em> and + may cause unrelated code to misbehave or crash the emulator.</p> </warning> <p>This function is thread-safe.</p> </desc> </func> <func> - <name><ret>void</ret><nametext>erl_drv_init_ack(ErlDrvPort port, + <name since="OTP 19.0"><ret>void</ret><nametext>erl_drv_init_ack(ErlDrvPort port, ErlDrvData res)</nametext></name> <fsummary>Acknowledge the start of the port.</fsummary> <desc> @@ -2340,7 +2345,7 @@ r = driver_async(myPort, &myKey, myData, myFunc); ]]></code> </func> <func> - <name><ret>ErlDrvTime</ret> + <name since="OTP 18.3"><ret>ErlDrvTime</ret> <nametext>erl_drv_monotonic_time(ErlDrvTimeUnit time_unit)</nametext> </name> <fsummary>Get Erlang monotonic time.</fsummary> @@ -2360,7 +2365,7 @@ r = driver_async(myPort, &myKey, myData, myFunc); ]]></code> </func> <func> - <name><ret>ErlDrvMutex *</ret><nametext>erl_drv_mutex_create(char + <name since=""><ret>ErlDrvMutex *</ret><nametext>erl_drv_mutex_create(char *name)</nametext></name> <fsummary>Create a mutex.</fsummary> <desc> @@ -2375,7 +2380,7 @@ r = driver_async(myPort, &myKey, myData, myFunc); ]]></code> </func> <func> - <name><ret>void</ret><nametext>erl_drv_mutex_destroy(ErlDrvMutex + <name since=""><ret>void</ret><nametext>erl_drv_mutex_destroy(ErlDrvMutex *mtx)</nametext></name> <fsummary>Destroy a mutex.</fsummary> <desc> @@ -2390,7 +2395,7 @@ r = driver_async(myPort, &myKey, myData, myFunc); ]]></code> </func> <func> - <name><ret>void</ret><nametext>erl_drv_mutex_lock(ErlDrvMutex + <name since=""><ret>void</ret><nametext>erl_drv_mutex_lock(ErlDrvMutex *mtx)</nametext></name> <fsummary>Lock a mutex.</fsummary> <desc> @@ -2409,7 +2414,7 @@ r = driver_async(myPort, &myKey, myData, myFunc); ]]></code> </func> <func> - <name><ret>char *</ret><nametext>erl_drv_mutex_name(ErlDrvMutex + <name since="OTP R16B02"><ret>char *</ret><nametext>erl_drv_mutex_name(ErlDrvMutex *mtx)</nametext></name> <fsummary>Get name of driver mutex.</fsummary> <desc> @@ -2423,7 +2428,7 @@ r = driver_async(myPort, &myKey, myData, myFunc); ]]></code> </func> <func> - <name><ret>int</ret><nametext>erl_drv_mutex_trylock(ErlDrvMutex + <name since=""><ret>int</ret><nametext>erl_drv_mutex_trylock(ErlDrvMutex *mtx)</nametext></name> <fsummary>Try lock a mutex.</fsummary> <desc> @@ -2442,7 +2447,7 @@ r = driver_async(myPort, &myKey, myData, myFunc); ]]></code> </func> <func> - <name><ret>void</ret><nametext>erl_drv_mutex_unlock(ErlDrvMutex + <name since=""><ret>void</ret><nametext>erl_drv_mutex_unlock(ErlDrvMutex *mtx)</nametext></name> <fsummary>Unlock a mutex.</fsummary> <desc> @@ -2455,7 +2460,7 @@ r = driver_async(myPort, &myKey, myData, myFunc); ]]></code> </func> <func> - <name><ret>int</ret><nametext>erl_drv_output_term(ErlDrvTermData port, + <name since="OTP R16B"><ret>int</ret><nametext>erl_drv_output_term(ErlDrvTermData port, ErlDrvTermData* term, int n)</nametext></name> <fsummary>Send term data from driver to port owner.</fsummary> <desc> @@ -2632,7 +2637,7 @@ erl_drv_output_term(driver_mk_port(drvport), spec, sizeof(spec) / sizeof(spec[0] </func> <func> - <name><ret>int</ret><nametext>erl_drv_putenv(const char *key, char + <name since=""><ret>int</ret><nametext>erl_drv_putenv(const char *key, char *value)</nametext></name> <fsummary>Set the value of an environment variable.</fsummary> <desc> @@ -2650,15 +2655,20 @@ erl_drv_output_term(driver_mk_port(drvport), spec, sizeof(spec) / sizeof(spec[0] environment variable is removed.</p> </note> <warning> - <p>Do <em>not</em> use libc's <c>putenv</c> or similar C library - interfaces from a driver.</p> + <p>This function modifies the emulated environment used by + <seealso marker="os:putenv/2"><c>os:putenv/2</c></seealso> and not + the environment used by libc's <c>putenv(3)</c> or similar. Drivers + that <em>require</em> that these are in sync will need to do so + themselves, but keep in mind that they are segregated for a reason; + <c>putenv(3)</c> and its friends are <em>not thread-safe</em> and + may cause unrelated code to misbehave or crash the emulator.</p> </warning> <p>This function is thread-safe.</p> </desc> </func> <func> - <name><ret>ErlDrvRWLock *</ret><nametext>erl_drv_rwlock_create(char + <name since=""><ret>ErlDrvRWLock *</ret><nametext>erl_drv_rwlock_create(char *name)</nametext></name> <fsummary>Create an rwlock.</fsummary> <desc> @@ -2674,7 +2684,7 @@ erl_drv_output_term(driver_mk_port(drvport), spec, sizeof(spec) / sizeof(spec[0] </func> <func> - <name><ret>void</ret><nametext>erl_drv_rwlock_destroy(ErlDrvRWLock + <name since=""><ret>void</ret><nametext>erl_drv_rwlock_destroy(ErlDrvRWLock *rwlck)</nametext></name> <fsummary>Destroy an rwlock.</fsummary> <desc> @@ -2689,7 +2699,7 @@ erl_drv_output_term(driver_mk_port(drvport), spec, sizeof(spec) / sizeof(spec[0] </func> <func> - <name><ret>char *</ret><nametext>erl_drv_rwlock_name(ErlDrvRWLock + <name since="OTP R16B02"><ret>char *</ret><nametext>erl_drv_rwlock_name(ErlDrvRWLock *rwlck)</nametext></name> <fsummary>Get name of driver mutex.</fsummary> <desc> @@ -2703,7 +2713,7 @@ erl_drv_output_term(driver_mk_port(drvport), spec, sizeof(spec) / sizeof(spec[0] </func> <func> - <name><ret>void</ret><nametext>erl_drv_rwlock_rlock(ErlDrvRWLock + <name since=""><ret>void</ret><nametext>erl_drv_rwlock_rlock(ErlDrvRWLock *rwlck)</nametext></name> <fsummary>Read lock an rwlock.</fsummary> <desc> @@ -2723,7 +2733,7 @@ erl_drv_output_term(driver_mk_port(drvport), spec, sizeof(spec) / sizeof(spec[0] </func> <func> - <name><ret>void</ret><nametext>erl_drv_rwlock_runlock(ErlDrvRWLock + <name since=""><ret>void</ret><nametext>erl_drv_rwlock_runlock(ErlDrvRWLock *rwlck)</nametext></name> <fsummary>Read unlock an rwlock.</fsummary> <desc> @@ -2736,7 +2746,7 @@ erl_drv_output_term(driver_mk_port(drvport), spec, sizeof(spec) / sizeof(spec[0] </func> <func> - <name><ret>void</ret><nametext>erl_drv_rwlock_rwlock(ErlDrvRWLock + <name since=""><ret>void</ret><nametext>erl_drv_rwlock_rwlock(ErlDrvRWLock *rwlck)</nametext></name> <fsummary>Read/write lock an rwlock.</fsummary> <desc> @@ -2756,7 +2766,7 @@ erl_drv_output_term(driver_mk_port(drvport), spec, sizeof(spec) / sizeof(spec[0] </func> <func> - <name><ret>void</ret><nametext>erl_drv_rwlock_rwunlock(ErlDrvRWLock + <name since=""><ret>void</ret><nametext>erl_drv_rwlock_rwunlock(ErlDrvRWLock *rwlck)</nametext></name> <fsummary>Read/write unlock an rwlock.</fsummary> <desc> @@ -2769,7 +2779,7 @@ erl_drv_output_term(driver_mk_port(drvport), spec, sizeof(spec) / sizeof(spec[0] </func> <func> - <name><ret>int</ret><nametext>erl_drv_rwlock_tryrlock(ErlDrvRWLock + <name since=""><ret>int</ret><nametext>erl_drv_rwlock_tryrlock(ErlDrvRWLock *rwlck)</nametext></name> <fsummary>Try to read lock an rwlock.</fsummary> <desc> @@ -2789,7 +2799,7 @@ erl_drv_output_term(driver_mk_port(drvport), spec, sizeof(spec) / sizeof(spec[0] </func> <func> - <name><ret>int</ret><nametext>erl_drv_rwlock_tryrwlock(ErlDrvRWLock + <name since=""><ret>int</ret><nametext>erl_drv_rwlock_tryrwlock(ErlDrvRWLock *rwlck)</nametext></name> <fsummary>Try to read/write lock an rwlock.</fsummary> <desc> @@ -2809,7 +2819,7 @@ erl_drv_output_term(driver_mk_port(drvport), spec, sizeof(spec) / sizeof(spec[0] </func> <func> - <name><ret>int</ret><nametext>erl_drv_send_term(ErlDrvTermData port, + <name since="OTP R16B"><ret>int</ret><nametext>erl_drv_send_term(ErlDrvTermData port, ErlDrvTermData receiver, ErlDrvTermData* term, int n)</nametext></name> <fsummary>Send term data to other process than port owner process. </fsummary> @@ -2833,7 +2843,7 @@ erl_drv_output_term(driver_mk_port(drvport), spec, sizeof(spec) / sizeof(spec[0] </func> <func> - <name><ret>void</ret><nametext>erl_drv_set_os_pid(ErlDrvPort port, + <name since="OTP 19.0"><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> @@ -2847,7 +2857,7 @@ erl_drv_output_term(driver_mk_port(drvport), spec, sizeof(spec) / sizeof(spec[0] </func> <func> - <name><ret>int</ret><nametext>erl_drv_thread_create(char *name, ErlDrvTid + <name since=""><ret>int</ret><nametext>erl_drv_thread_create(char *name, ErlDrvTid *tid, void * (*func)(void *), void *arg, ErlDrvThreadOpts *opts)</nametext></name> <fsummary>Create a thread.</fsummary> @@ -2910,7 +2920,7 @@ erl_drv_output_term(driver_mk_port(drvport), spec, sizeof(spec) / sizeof(spec[0] </func> <func> - <name><ret>void</ret><nametext>erl_drv_thread_exit(void + <name since=""><ret>void</ret><nametext>erl_drv_thread_exit(void *exit_value)</nametext></name> <fsummary>Terminate calling thread.</fsummary> <desc> @@ -2929,7 +2939,7 @@ erl_drv_output_term(driver_mk_port(drvport), spec, sizeof(spec) / sizeof(spec[0] </func> <func> - <name><ret>int</ret><nametext>erl_drv_thread_join(ErlDrvTid tid, void + <name since=""><ret>int</ret><nametext>erl_drv_thread_join(ErlDrvTid tid, void **exit_value)</nametext></name> <fsummary>Join with another thread.</fsummary> <desc> @@ -2952,7 +2962,7 @@ erl_drv_output_term(driver_mk_port(drvport), spec, sizeof(spec) / sizeof(spec[0] </func> <func> - <name><ret>char *</ret><nametext>erl_drv_thread_name(ErlDrvTid + <name since="OTP R16B02"><ret>char *</ret><nametext>erl_drv_thread_name(ErlDrvTid tid)</nametext></name> <fsummary>Get name of driver mutex.</fsummary> <desc> @@ -2966,7 +2976,7 @@ erl_drv_output_term(driver_mk_port(drvport), spec, sizeof(spec) / sizeof(spec[0] </func> <func> - <name><ret>ErlDrvThreadOpts *</ret> + <name since=""><ret>ErlDrvThreadOpts *</ret> <nametext>erl_drv_thread_opts_create(char *name)</nametext></name> <fsummary>Create thread options.</fsummary> <desc> @@ -2995,7 +3005,7 @@ erl_drv_output_term(driver_mk_port(drvport), spec, sizeof(spec) / sizeof(spec[0] </func> <func> - <name><ret>void</ret> + <name since=""><ret>void</ret> <nametext>erl_drv_thread_opts_destroy(ErlDrvThreadOpts *opts)</nametext> </name> <fsummary>Destroy thread options.</fsummary> @@ -3010,7 +3020,7 @@ erl_drv_output_term(driver_mk_port(drvport), spec, sizeof(spec) / sizeof(spec[0] </func> <func> - <name><ret>ErlDrvTid</ret> + <name since=""><ret>ErlDrvTid</ret> <nametext>erl_drv_thread_self(void)</nametext></name> <fsummary>Get the thread identifier of the current thread.</fsummary> <desc> @@ -3021,7 +3031,7 @@ erl_drv_output_term(driver_mk_port(drvport), spec, sizeof(spec) / sizeof(spec[0] </func> <func> - <name><ret>ErlDrvTime</ret><nametext>erl_drv_time_offset(ErlDrvTimeUnit + <name since="OTP 18.3"><ret>ErlDrvTime</ret><nametext>erl_drv_time_offset(ErlDrvTimeUnit time_unit)</nametext></name> <fsummary>Get current time offset.</fsummary> <desc> @@ -3044,7 +3054,7 @@ erl_drv_output_term(driver_mk_port(drvport), spec, sizeof(spec) / sizeof(spec[0] </func> <func> - <name><ret>void *</ret><nametext>erl_drv_tsd_get(ErlDrvTSDKey + <name since=""><ret>void *</ret><nametext>erl_drv_tsd_get(ErlDrvTSDKey key)</nametext></name> <fsummary>Get thread-specific data.</fsummary> <desc> @@ -3059,7 +3069,7 @@ erl_drv_output_term(driver_mk_port(drvport), spec, sizeof(spec) / sizeof(spec[0] </func> <func> - <name><ret>int</ret><nametext>erl_drv_tsd_key_create(char *name, + <name since=""><ret>int</ret><nametext>erl_drv_tsd_key_create(char *name, ErlDrvTSDKey *key)</nametext></name> <fsummary>Create a thread-specific data key.</fsummary> <desc> @@ -3076,7 +3086,7 @@ erl_drv_output_term(driver_mk_port(drvport), spec, sizeof(spec) / sizeof(spec[0] </func> <func> - <name><ret>void</ret><nametext>erl_drv_tsd_key_destroy(ErlDrvTSDKey + <name since=""><ret>void</ret><nametext>erl_drv_tsd_key_destroy(ErlDrvTSDKey key)</nametext></name> <fsummary>Destroy a thread-specific data key.</fsummary> <desc> @@ -3101,7 +3111,7 @@ erl_drv_output_term(driver_mk_port(drvport), spec, sizeof(spec) / sizeof(spec[0] </func> <func> - <name><ret>void</ret><nametext>erl_drv_tsd_set(ErlDrvTSDKey key, void + <name since=""><ret>void</ret><nametext>erl_drv_tsd_set(ErlDrvTSDKey key, void *data)</nametext></name> <fsummary>Set thread-specific data.</fsummary> <desc> @@ -3128,7 +3138,7 @@ erl_drv_output_term(driver_mk_port(drvport), spec, sizeof(spec) / sizeof(spec[0] </func> <func> - <name><ret>char *</ret><nametext>erl_errno_id(int error)</nametext></name> + <name since=""><ret>char *</ret><nametext>erl_errno_id(int error)</nametext></name> <fsummary>Get Erlang error atom name from error number.</fsummary> <desc> <marker id="erl_errno_id"></marker> @@ -3140,7 +3150,7 @@ erl_drv_output_term(driver_mk_port(drvport), spec, sizeof(spec) / sizeof(spec[0] </func> <func> - <name><ret>int</ret><nametext>remove_driver_entry(ErlDrvEntry + <name since=""><ret>int</ret><nametext>remove_driver_entry(ErlDrvEntry *de)</nametext></name> <fsummary>Remove a driver entry.</fsummary> <desc> @@ -3154,7 +3164,7 @@ erl_drv_output_term(driver_mk_port(drvport), spec, sizeof(spec) / sizeof(spec[0] </func> <func> - <name><ret>void</ret><nametext>set_busy_port(ErlDrvPort port, int + <name since=""><ret>void</ret><nametext>set_busy_port(ErlDrvPort port, int on)</nametext></name> <fsummary>Signal or unsignal port as busy.</fsummary> <desc> @@ -3185,7 +3195,7 @@ erl_drv_output_term(driver_mk_port(drvport), spec, sizeof(spec) / sizeof(spec[0] </func> <func> - <name><ret>void</ret><nametext>set_port_control_flags(ErlDrvPort port, + <name since=""><ret>void</ret><nametext>set_port_control_flags(ErlDrvPort port, int flags)</nametext></name> <fsummary>Set flags on how to handle control entry function.</fsummary> <desc> @@ -3210,6 +3220,6 @@ erl_drv_output_term(driver_mk_port(drvport), spec, sizeof(spec) / sizeof(spec[0] <seealso marker="erlang"><c>erlang(3)</c></seealso>, <seealso marker="kernel:erl_ddll"><c>erl_ddll(3)</c></seealso>, section <seealso marker="alt_dist">How to Implement an Alternative - Carrier for the Erlang Distribution></seealso> in the User's Guide</p> + Carrier for the Erlang Distribution</seealso> in the User's Guide</p> </section> </cref> diff --git a/erts/doc/src/erl_ext_dist.xml b/erts/doc/src/erl_ext_dist.xml index 4f799f8f34..b7090d0472 100644 --- a/erts/doc/src/erl_ext_dist.xml +++ b/erts/doc/src/erl_ext_dist.xml @@ -5,7 +5,7 @@ <header> <copyright> <year>2007</year> - <year>2016</year> + <year>2017</year> <holder>Ericsson AB, All Rights Reserved</holder> </copyright> <legalnotice> @@ -51,7 +51,7 @@ term into the external format. To convert binary data encoding to a term, the BIF <seealso marker="erts:erlang#binary_to_term/1"> - <c>erlang:binary_to_term/1</c>c></seealso> is used. + <c>erlang:binary_to_term/1</c></seealso> is used. </p> <p> The distribution does this implicitly when sending messages across @@ -119,27 +119,18 @@ <tcaption>Compressed Data Format when Expanded</tcaption></table> <marker id="utf8_atoms"/> <note> - <p>As from ERTS 5.10 (OTP R16) support - for UTF-8 encoded atoms has been introduced in the external format. - However, only characters that can be encoded using Latin-1 (ISO-8859-1) - are currently supported in atoms. The support for UTF-8 encoded atoms - in the external format has been implemented to be able to support - 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 Latin-1, and <em>the behavior is - undefined</em>.</p> - <p>When distribution flag <seealso marker="erl_dist_protocol#dflags"> - <c>DFLAG_UTF8_ATOMS</c></seealso> has been exchanged between both nodes - in the <seealso marker="erl_dist_protocol#distribution_handshake"> - distribution handshake</seealso>, all atoms in the distribution header - are encoded in UTF-8, otherwise in Latin-1. The two - new tags <seealso marker="#ATOM_UTF8_EXT"><c>ATOM_UTF8_EXT</c></seealso> - and <seealso marker="#SMALL_ATOM_UTF8_EXT"> - <c>SMALL_ATOM_UTF8_EXT</c></seealso> - are only used if the distribution flag <c>DFLAG_UTF8_ATOMS</c> has - been exchanged between nodes, or if an atom containing characters - that cannot be encoded in Latin-1 is encountered.</p> + <p>As from ERTS 9.0 (OTP 20), atoms may contain any Unicode + characters and are always encoded using the UTF-8 external formats + <seealso marker="#ATOM_UTF8_EXT"><c>ATOM_UTF8_EXT</c></seealso> + or <seealso marker="#SMALL_ATOM_UTF8_EXT"><c>SMALL_ATOM_UTF8_EXT</c></seealso>. + The old Latin-1 formats <seealso marker="#ATOM_EXT"><c>ATOM_EXT</c></seealso> + and <seealso marker="#SMALL_ATOM_EXT"><c>SMALL_ATOM_EXT</c></seealso> + are deprecated and are only kept for backward + compatibility when decoding terms encoded by older nodes.</p> + <p>Support for UTF-8 encoded atoms in the external format has been + available since ERTS 5.10 (OTP R16). This abillity allows such old nodes + to decode, store and encode any Unicode atoms received from a new OTP 20 + node.</p> <p>The maximum number of allowed characters in an atom is 255. In the UTF-8 case, each character can need 4 bytes to be encoded.</p> </note> @@ -395,28 +386,6 @@ </section> <section> - <marker id="ATOM_EXT"/> - <title>ATOM_EXT</title> - <table align="left"> - <row> - <cell align="center">1</cell> - <cell align="center">2</cell> - <cell align="center">Len</cell> - </row> - <row> - <cell align="center"><c>100</c></cell> - <cell align="center"><c>Len</c></cell> - <cell align="center"><c>AtomName</c></cell> - </row> - <tcaption>ATOM_EXT</tcaption></table> - <p> - An atom is stored with a 2 byte unsigned length in big-endian order, - followed by <c>Len</c> numbers of 8-bit Latin-1 characters that forms - the <c>AtomName</c>. The maximum allowed value for <c>Len</c> is 255. - </p> - </section> - - <section> <marker id="REFERENCE_EXT"/> <title>REFERENCE_EXT</title> <table align="left"> @@ -437,8 +406,8 @@ Encodes a reference object (an object generated with <seealso marker="erlang:make_ref/0">erlang:make_ref/0</seealso>). The <c>Node</c> term is an encoded atom, that is, - <seealso marker="#ATOM_EXT"><c>ATOM_EXT</c></seealso>, - <seealso marker="#SMALL_ATOM_EXT"><c>SMALL_ATOM_EXT</c></seealso>, or + <seealso marker="#ATOM_UTF8_EXT"><c>ATOM_UTF8_EXT</c></seealso>, + <seealso marker="#SMALL_ATOM_UTF8_EXT"><c>SMALL_ATOM_UTF8_EXT</c></seealso>, or <seealso marker="#ATOM_CACHE_REF"><c>ATOM_CACHE_REF</c></seealso>. The <c>ID</c> field contains a big-endian unsigned integer, but <em>is to be regarded as uninterpreted data</em>, @@ -777,39 +746,6 @@ </section> <section> - <marker id="SMALL_ATOM_EXT"/> - <title>SMALL_ATOM_EXT</title> - <table align="left"> - <row> - <cell align="center">1</cell> - <cell align="center">1</cell> - <cell align="center">Len</cell> - </row> - <row> - <cell align="center"><c>115</c></cell> - <cell align="center"><c>Len</c></cell> - <cell align="center"><c>AtomName</c></cell> - </row> - <tcaption>SMALL_ATOM_EXT</tcaption></table> - <p> - An atom is stored with a 1 byte unsigned length, - followed by <c>Len</c> numbers of 8-bit Latin-1 characters that - forms the <c>AtomName</c>. Longer atoms can be represented - by <seealso marker="#ATOM_EXT"><c>ATOM_EXT</c></seealso>. - </p> - <note> - <p> - <c>SMALL_ATOM_EXT</c> was introduced in ERTS 5.7.2 and - require an exchange of distribution flag - <seealso marker="erl_dist_protocol#dflags"> - <c>DFLAG_SMALL_ATOM_TAGS</c></seealso> in the - <seealso marker="erl_dist_protocol#distribution_handshake"> - distribution handshake</seealso>. - </p> - </note> - </section> - - <section> <marker id="FUN_EXT"/> <title>FUN_EXT</title> <table align="left"> @@ -843,8 +779,8 @@ <tag><c>Module</c></tag> <item> <p>Encoded as an atom, using - <seealso marker="#ATOM_EXT"><c>ATOM_EXT</c></seealso>, - <seealso marker="#SMALL_ATOM_EXT"><c>SMALL_ATOM_EXT</c></seealso>, + <seealso marker="#ATOM_UTF8_EXT"><c>ATOM_UTF8_EXT</c></seealso>, + <seealso marker="#SMALL_ATOM_UTF8_EXT"><c>SMALL_ATOM_UTF8_EXT</c></seealso>, or <seealso marker="#ATOM_CACHE_REF"> <c>ATOM_CACHE_REF</c></seealso>. This is the module that the fun is implemented in. @@ -938,8 +874,8 @@ <tag><c>Module</c></tag> <item> <p>Encoded as an atom, using - <seealso marker="#ATOM_EXT"><c>ATOM_EXT</c></seealso>, - <seealso marker="#SMALL_ATOM_EXT"><c>SMALL_ATOM_EXT</c></seealso>, + <seealso marker="#ATOM_EXT"><c>ATOM_UTF8_EXT</c></seealso>, + <seealso marker="#SMALL_ATOM_EXT"><c>SMALL_ATOM_UTF8_EXT</c></seealso>, or <seealso marker="#ATOM_CACHE_REF"> <c>ATOM_CACHE_REF</c></seealso>. Is the module that the fun is implemented in. @@ -1001,8 +937,8 @@ </p> <p> <c>Module</c> and <c>Function</c> are atoms - (encoded using <seealso marker="#ATOM_EXT"><c>ATOM_EXT</c></seealso>, - <seealso marker="#SMALL_ATOM_EXT"><c>SMALL_ATOM_EXT</c></seealso>, or + (encoded using <seealso marker="#ATOM_EXT"><c>ATOM_UTF8_EXT</c></seealso>, + <seealso marker="#SMALL_ATOM_EXT"><c>SMALL_ATOM_UTF8_EXT</c></seealso>, or <seealso marker="#ATOM_CACHE_REF"><c>ATOM_CACHE_REF</c></seealso>). </p> <p> @@ -1114,6 +1050,61 @@ in the beginning of this section. </p> </section> + + <section> + <marker id="ATOM_EXT"/> + <title>ATOM_EXT (deprecated)</title> + <table align="left"> + <row> + <cell align="center">1</cell> + <cell align="center">2</cell> + <cell align="center">Len</cell> + </row> + <row> + <cell align="center"><c>100</c></cell> + <cell align="center"><c>Len</c></cell> + <cell align="center"><c>AtomName</c></cell> + </row> + <tcaption>ATOM_EXT</tcaption></table> + <p> + An atom is stored with a 2 byte unsigned length in big-endian order, + followed by <c>Len</c> numbers of 8-bit Latin-1 characters that forms + the <c>AtomName</c>. The maximum allowed value for <c>Len</c> is 255. + </p> + </section> + + <section> + <marker id="SMALL_ATOM_EXT"/> + <title>SMALL_ATOM_EXT (deprecated)</title> + <table align="left"> + <row> + <cell align="center">1</cell> + <cell align="center">1</cell> + <cell align="center">Len</cell> + </row> + <row> + <cell align="center"><c>115</c></cell> + <cell align="center"><c>Len</c></cell> + <cell align="center"><c>AtomName</c></cell> + </row> + <tcaption>SMALL_ATOM_EXT</tcaption></table> + <p> + An atom is stored with a 1 byte unsigned length, + followed by <c>Len</c> numbers of 8-bit Latin-1 characters that + forms the <c>AtomName</c>. + </p> + <note> + <p> + <c>SMALL_ATOM_EXT</c> was introduced in ERTS 5.7.2 and + require an exchange of distribution flag + <seealso marker="erl_dist_protocol#dflags"> + <c>DFLAG_SMALL_ATOM_TAGS</c></seealso> in the + <seealso marker="erl_dist_protocol#distribution_handshake"> + distribution handshake</seealso>. + </p> + </note> + </section> + </chapter> diff --git a/erts/doc/src/erl_nif.xml b/erts/doc/src/erl_nif.xml index b5dc9037c4..5cbeddabd9 100644 --- a/erts/doc/src/erl_nif.xml +++ b/erts/doc/src/erl_nif.xml @@ -4,7 +4,7 @@ <cref> <header> <copyright> - <year>2001</year><year>2016</year> + <year>2001</year><year>2018</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -80,7 +80,7 @@ <code type="none"> /* niftest.c */ -#include "erl_nif.h" +#include <erl_nif.h> static ERL_NIF_TERM hello(ErlNifEnv* env, int argc, const ERL_NIF_TERM argv[]) { @@ -123,7 +123,7 @@ ok "Hello world!"</code> <p>A better solution for a real module is to take advantage of the new - directive <c>on load</c> (see section + directive <c>on_load</c> (see section <seealso marker="doc/reference_manual:code_loading#on_load">Running a Function When a Module is Loaded</seealso> in the Erlang Reference Manual) to load the NIF library automatically when the module is @@ -135,27 +135,14 @@ ok away by the compiler, causing loading of the NIF library to fail.</p> </note> - <p>A loaded NIF library is tied to the Erlang module code version - that loaded it. If the module is upgraded with a new version, the - new Erlang code need to load its own NIF library (or maybe choose not - to). The new code version can, however, choose to load the - same NIF library as the old code if it wants to. Sharing the - dynamic library means that static data defined by the library - is shared as well. To avoid unintentionally shared static - data, each Erlang module code can keep its own private data. This - private data can be set when the NIF library is loaded and - then retrieved by calling <seealso marker="#enif_priv_data"> - <c>enif_priv_data</c></seealso>.</p> - - <p>A NIF library cannot be loaded explicitly. A library is - automatically unloaded when the module code that it belongs to is purged - by the code server.</p> + <p>Once loaded, a NIF library is persistent. It will not be unloaded + until the module code version that it belongs to is purged.</p> </description> <section> <title>Functionality</title> - <p>All functions that a NIF library needs to do with Erlang are - performed through the NIF API functions. Functions exist + <p>All interaction between NIF code and the Erlang runtime system is + performed by calling NIF API functions. Functions exist for the following functionality:</p> <taglist> @@ -207,7 +194,7 @@ ok <p>Binaries are sequences of whole bytes. Bitstrings with an arbitrary bit length have no support yet.</p> </item> - <tag>Resource objects</tag> + <tag><marker id="resource_objects"/>Resource objects</tag> <item> <p>The use of resource objects is a safe way to return pointers to native data structures from a NIF. A resource object is @@ -219,7 +206,7 @@ ok <seealso marker="#enif_make_resource"> <c>enif_make_resource</c></seealso>. The term returned by <c>enif_make_resource</c> is opaque in nature. - It can be stored and passed between processes on the same node, but + It can be stored and passed between processes, but the only real end usage is to pass it back as an argument to a NIF. The NIF can then call <seealso marker="#enif_get_resource"> <c>enif_get_resource</c></seealso> and get back a pointer to the @@ -286,6 +273,19 @@ return term;</code> library is postponed as long as there exist resource objects with a destructor function in the library.</p> </item> + <tag>Module upgrade and static data</tag> + <item> + <p>A loaded NIF library is tied to the Erlang module instance + that loaded it. If the module is upgraded, the new module instance + needs to load its own NIF library (or maybe choose not to). The new + module instance can, however, choose to load the exact same NIF library + as the old code if it wants to. Sharing the dynamic library means that + static data defined by the library is shared as well. To avoid + unintentionally shared static data between module instances, each Erlang + module version can keep its own private data. This private data can be + set when the NIF library is loaded and later retrieved by calling + <seealso marker="#enif_priv_data"><c>enif_priv_data</c></seealso>.</p> + </item> <tag>Threads and concurrency</tag> <item> <p>A NIF is thread-safe without any explicit synchronization as @@ -293,11 +293,11 @@ return term;</code> arguments. When you write to a shared state either through static variables or <seealso marker="#enif_priv_data"> <c>enif_priv_data</c></seealso>, you need to supply your own explicit - synchronization. This includes terms in process-independent + synchronization. This includes terms in process independent environments that are shared between threads. Resource objects also require synchronization if you treat them as mutable.</p> - <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> + <p>The library initialization callbacks <c>load</c> and + <c>upgrade</c> are thread-safe even for shared state data.</p> </item> <tag><marker id="version_management"/>Version Management</tag> <item> @@ -344,6 +344,83 @@ return term;</code> <c>enif_convert_time_unit()</c></seealso></item> </list> </item> + <tag><marker id="enif_ioq"/>I/O Queues</tag> + <item> + <p>The Erlang nif library contains function for easily working + with I/O vectors as used by the unix system call <c>writev</c>. + The I/O Queue is not thread safe, so some other synchronization + mechanism has to be used.</p> + <list type="bulleted"> + <item><seealso marker="#SysIOVec"> + <c>SysIOVec</c></seealso></item> + <item><seealso marker="#ErlNifIOVec"> + <c>ErlNifIOVec</c></seealso></item> + <item><seealso marker="#enif_ioq_create"> + <c>enif_ioq_create()</c></seealso></item> + <item><seealso marker="#enif_ioq_destroy"> + <c>enif_ioq_destroy()</c></seealso></item> + <item><seealso marker="#enif_ioq_enq_binary"> + <c>enif_ioq_enq_binary()</c></seealso></item> + <item><seealso marker="#enif_ioq_enqv"> + <c>enif_ioq_enqv()</c></seealso></item> + <item><seealso marker="#enif_ioq_deq"> + <c>enif_ioq_deq()</c></seealso></item> + <item><seealso marker="#enif_ioq_peek"> + <c>enif_ioq_peek()</c></seealso></item> + <item><seealso marker="#enif_ioq_peek_head"> + <c>enif_ioq_peek_head()</c></seealso></item> + <item><seealso marker="#enif_inspect_iovec"> + <c>enif_inspect_iovec()</c></seealso></item> + <item><seealso marker="#enif_free_iovec"> + <c>enif_free_iovec()</c></seealso></item> + </list> + <p>Typical usage when writing to a file descriptor looks like this:</p> + <code type="none"><![CDATA[ +int writeiovec(ErlNifEnv *env, ERL_NIF_TERM term, ERL_NIF_TERM *tail, + ErlNifIOQueue *q, int fd) { + + ErlNifIOVec vec, *iovec = &vec; + SysIOVec *sysiovec; + int saved_errno; + int iovcnt, n; + + if (!enif_inspect_iovec(env, 64, term, tail, &iovec)) + return -2; + + if (enif_ioq_size(q) > 0) { + /* If the I/O queue contains data we enqueue the iovec and + then peek the data to write out of the queue. */ + if (!enif_ioq_enqv(q, iovec, 0)) + return -3; + + sysiovec = enif_ioq_peek(q, &iovcnt); + } else { + /* If the I/O queue is empty we skip the trip through it. */ + iovcnt = iovec->iovcnt; + sysiovec = iovec->iov; + } + + /* Attempt to write the data */ + n = writev(fd, sysiovec, iovcnt); + saved_errno = errno; + + if (enif_ioq_size(q) == 0) { + /* If the I/O queue was initially empty we enqueue any + remaining data into the queue for writing later. */ + if (n >= 0 && !enif_ioq_enqv(q, iovec, n)) + return -3; + } else { + /* Dequeue any data that was written from the queue. */ + if (n > 0 && !enif_ioq_deq(q, n, NULL)) + return -4; + } + + /* return n, which is either number of bytes written or -1 if + some error happened */ + errno = saved_errno; + return n; +}]]></code> + </item> <tag><marker id="lengthy_work"/>Long-running NIFs</tag> <item> <p>As mentioned in the <seealso marker="#WARNING">warning</seealso> text @@ -402,14 +479,14 @@ return term;</code> <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 disabled by default. The Erlang runtime - without SMP support does not support dirty schedulers even when - the dirty scheduler support is enabled. To check at runtime for - the presence of dirty scheduler threads, code can use the - <seealso marker="#enif_system_info"> + <p>Dirty NIF support is available only when the emulator is + configured with dirty scheduler support. As of ERTS version + 9.0, dirty scheduler support is enabled by default on the + runtime system with SMP support. The Erlang runtime without + SMP support does <em>not</em> support dirty schedulers even + when the dirty scheduler support is explicitly 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 @@ -463,7 +540,7 @@ return term;</code> have to wait for a very long time. Blocking multi-scheduling, that is, calling <seealso marker="erlang#system_flag_multi_scheduling"> <c>erlang:system_flag(multi_scheduling, block)</c></seealso>, can - also take a very long time to complete. This becaue all ongoing + also take a very long time to complete. This is because all ongoing dirty operations on all dirty schedulers must complete before the block operation can complete.</p> <p>Many operations communicating with a process executing a @@ -498,7 +575,7 @@ return term;</code> <title>Initialization</title> <taglist> <tag><marker id="ERL_NIF_INIT"/><c>ERL_NIF_INIT(MODULE, - ErlNifFunc funcs[], load, reload, upgrade, unload)</c></tag> + ErlNifFunc funcs[], load, NULL, upgrade, unload)</c></tag> <item> <p>This is the magic macro to initialize a NIF library. It is to be evaluated in global file scope.</p> @@ -507,22 +584,25 @@ return term;</code> the macro.</p> <p><c>funcs</c> is a static array of function descriptors for all the implemented NIFs in this library.</p> - <p><c>load</c>, <c>reload</c>, <c>upgrade</c> and <c>unload</c> - are pointers to functions. One of <c>load</c>, <c>reload</c>, or + <p><c>load</c>, <c>upgrade</c> and <c>unload</c> + are pointers to functions. One of <c>load</c> or <c>upgrade</c> is called to initialize the library. <c>unload</c> is called to release the library. All are described individually below.</p> + <p>The fourth argument <c>NULL</c> is ignored. It + was earlier used for the deprecated <c>reload</c> callback + which is no longer supported since OTP 20.</p> <p>If compiling a NIF for static inclusion through <c>--enable-static-nifs</c>, you must define <c>STATIC_ERLANG_NIF</c> before the <c>ERL_NIF_INIT</c> declaration.</p> </item> - <tag><marker id="load"/><c>int (*load)(ErlNifEnv* env, void** priv_data, + <tag><marker id="load"/><c>int (*load)(ErlNifEnv* caller_env, void** priv_data, ERL_NIF_TERM load_info)</c></tag> <item> <p><c>load</c> is called when the NIF library is loaded and no previously loaded library exists for this module.</p> <p><c>*priv_data</c> can be set to point to some private data - that the library needs to keep a state between NIF + if the library needs to keep a state between NIF calls. <c>enif_priv_data</c> returns this pointer. <c>*priv_data</c> is initialized to <c>NULL</c> when <c>load</c> is called.</p> @@ -532,46 +612,26 @@ return term;</code> anything other than <c>0</c>. <c>load</c> can be <c>NULL</c> if initialization is not needed.</p> </item> - <tag><marker id="upgrade"/><c>int (*upgrade)(ErlNifEnv* env, void** + <tag><marker id="upgrade"/><c>int (*upgrade)(ErlNifEnv* caller_env, void** priv_data, void** old_priv_data, ERL_NIF_TERM load_info)</c></tag> <item> <p><c>upgrade</c> is called when the NIF library is loaded and there is old code of this module with a loaded NIF library.</p> <p>Works as <c>load</c>, except that <c>*old_priv_data</c> already contains the value set by the last call to <c>load</c> or - <c>reload</c> for the old module code. <c>*priv_data</c> is + <c>upgrade</c> for the old module code. <c>*priv_data</c> is initialized to <c>NULL</c> when <c>upgrade</c> is called. It is allowed to write to both <c>*priv_data</c> and <c>*old_priv_data.</c></p> <p>The library fails to load if <c>upgrade</c> returns anything other than <c>0</c> or if <c>upgrade</c> is <c>NULL</c>.</p> </item> - <tag><marker id="unload"/><c>void (*unload)(ErlNifEnv* env, void* + <tag><marker id="unload"/><c>void (*unload)(ErlNifEnv* caller_env, void* priv_data)</c></tag> <item> <p><c>unload</c> is called when the module code that the NIF library belongs to is purged as old. New code of the same - module may or may not exist. Notice that <c>unload</c> is not - called for a replaced library as a consequence of <c>reload</c>.</p> - </item> - <tag><marker id="reload"/><c>int (*reload)(ErlNifEnv* env, void** - priv_data, ERL_NIF_TERM load_info)</c></tag> - <item> - <note> - <p><em>The reload mechanism is deprecated.</em> It was only intended - as a development feature. Do not use it as an upgrade method for - live production systems. It can be removed in future releases. - Ensure to pass <c>reload</c> as <c>NULL</c> to - <seealso marker="#ERL_NIF_INIT"><c>ERL_NIF_INIT</c></seealso> - to disable it when not used.</p> - </note> - <p><c>reload</c> is called when the NIF library is loaded and a - previously loaded library already exists for this module code.</p> - <p>Works as <c>load</c>, except that - <c>*priv_data</c> already contains the value set by the - previous call to <c>load</c> or <c>reload</c>.</p> - <p>The library fails to load if <c>reload</c> returns - anything other than <c>0</c> or if <c>reload</c> is <c>NULL</c>.</p> + module may or may not exist.</p> </item> </taglist> </section> @@ -594,27 +654,41 @@ return term;</code> <p><c>ErlNifEnv</c> represents an environment that can host Erlang terms. All terms in an environment are valid as long as the environment is valid. <c>ErlNifEnv</c> is an opaque type; pointers to - it can only be passed on to API functions. Two types of environments + it can only be passed on to API functions. Three types of environments exist:</p> <taglist> - <tag>Process-bound environment</tag> + <tag>Process bound environment</tag> <item> <p>Passed as the first argument to all NIFs. All function arguments passed to a NIF belong to that environment. The return value from a NIF must also be a term belonging to the same environment.</p> - <p>A process-bound environment contains transient information + <p>A process bound environment contains transient information about the calling Erlang process. The environment is only valid in the thread where it was supplied as argument until the NIF returns. It is thus useless and dangerous to store pointers to - process-bound environments between NIF calls.</p> + process bound environments between NIF calls.</p> </item> - <tag>Process-independent environment</tag> + <tag>Callback environment</tag> + <item> + <p>Passed as the first argument to all the non-NIF callback functions + (<seealso marker="#load"><c>load</c></seealso>, + <seealso marker="#upgrade"><c>upgrade</c></seealso>, + <seealso marker="#unload"><c>unload</c></seealso>, + <seealso marker="#ErlNifResourceDtor"><c>dtor</c></seealso>, + <seealso marker="#ErlNifResourceDown"><c>down</c></seealso> and + <seealso marker="#ErlNifResourceStop"><c>stop</c></seealso>). + Works like a process bound environment but with a temporary + pseudo process that "terminates" when the callback has + returned. Terms may be created in this environment but they will + only be accessible during the callback.</p> + </item> + <tag>Process independent environment</tag> <item> <p>Created by calling <seealso marker="#enif_alloc_env"> <c>enif_alloc_env</c></seealso>. This environment can be used to store terms between NIF calls and to send terms with <seealso marker="#enif_send"><c>enif_send</c></seealso>. A - process-independent environment with all its terms is valid until + process independent environment with all its terms is valid until you explicitly invalidate it with <seealso marker="#enif_free_env"><c>enif_free_env</c></seealso> or <c>enif_send</c>.</p> @@ -659,9 +733,6 @@ typedef struct { <p><c>flags</c> can be used to indicate that the NIF is a <seealso marker="#dirty_nifs">dirty NIF</seealso> that is to be executed on a dirty scheduler thread.</p> - <p><em>The dirty NIF functionality described here is - experimental.</em> You have to enable support for dirty - schedulers when building OTP to try out the functionality.</p> <p>If the dirty NIF is expected to be CPU-bound, its <c>flags</c> field is to be set to <c>ERL_NIF_DIRTY_JOB_CPU_BOUND</c> or <c>ERL_NIF_DIRTY_JOB_IO_BOUND</c>.</p> @@ -695,6 +766,18 @@ typedef struct { <p>When receiving data from untrusted sources, use option <c>ERL_NIF_BIN2TERM_SAFE</c>.</p> </item> + <tag><marker id="ErlNifMonitor"/><c>ErlNifMonitor</c></tag> + <item> + <p>This is an opaque data type that identifies a monitor.</p> + <p>The nif writer is to provide the memory for storing the + monitor when calling <seealso marker="#enif_monitor_process"> + <c>enif_monitor_process</c></seealso>. The + address of the data is not stored by the runtime system, so + <c>ErlNifMonitor</c> can be used as any other data, it + can be copied, moved in memory, forgotten, and so on. + To compare two monitors, <seealso marker="#enif_compare_monitors"> + <c>enif_compare_monitors</c></seealso> must be used.</p> + </item> <tag><marker id="ErlNifPid"/><c>ErlNifPid</c></tag> <item> <p>A process identifier (pid). In contrast to pid terms (instances of @@ -716,11 +799,47 @@ typedef struct { Each resource type has a unique name and a destructor function that is called when objects of its type are released.</p> </item> + <tag><marker id="ErlNifResourceTypeInit"/><c>ErlNifResourceTypeInit</c></tag> + <item> + <code type="none"> +typedef struct { + ErlNifResourceDtor* dtor; + ErlNifResourceStop* stop; + ErlNifResourceDown* down; +} ErlNifResourceTypeInit;</code> + <p>Initialization structure read by <seealso marker="#enif_open_resource_type_x"> + enif_open_resource_type_x</seealso>.</p> + </item> <tag><marker id="ErlNifResourceDtor"/><c>ErlNifResourceDtor</c></tag> <item> <code type="none"> -typedef void ErlNifResourceDtor(ErlNifEnv* env, void* obj);</code> +typedef void ErlNifResourceDtor(ErlNifEnv* caller_env, void* obj);</code> <p>The function prototype of a resource destructor function.</p> + <p>The <c>obj</c> argument is a pointer to the resource. The only + allowed use for the resource in the destructor is to access its + user data one final time. The destructor is guaranteed to be the + last callback before the resource is deallocated.</p> + </item> + <tag><marker id="ErlNifResourceDown"/><c>ErlNifResourceDown</c></tag> + <item> + <code type="none"> +typedef void ErlNifResourceDown(ErlNifEnv* caller_env, void* obj, ErlNifPid* pid, ErlNifMonitor* mon);</code> + <p>The function prototype of a resource down function, + called on the behalf of <seealso marker="#enif_monitor_process"> + enif_monitor_process</seealso>. <c>obj</c> is the resource, <c>pid</c> + is the identity of the monitored process that is exiting, and <c>mon</c> + is the identity of the monitor. + </p> + </item> + <tag><marker id="ErlNifResourceStop"/><c>ErlNifResourceStop</c></tag> + <item> + <code type="none"> +typedef void ErlNifResourceStop(ErlNifEnv* caller_env, void* obj, ErlNifEvent event, int is_direct_call);</code> + <p>The function prototype of a resource stop function, + called on the behalf of <seealso marker="#enif_select"> + enif_select</seealso>. <c>obj</c> is the resource, <c>event</c> is OS event, + <c>is_direct_call</c> is true if the call is made directly from <c>enif_select</c> + or false if it is a scheduled call (potentially from another thread).</p> </item> <tag><marker id="ErlNifCharEncoding"/><c>ErlNifCharEncoding</c></tag> <item> @@ -770,7 +889,7 @@ typedef enum { <item> <p>An enumeration of the properties that can be requested from <seealso marker="#enif_make_unique_integer"> - <c>enif_unique_integer</c></seealso>. + <c>enif_make_unique_integer</c></seealso>. For default properties, use value <c>0</c>.</p> <taglist> <tag><c>ERL_NIF_UNIQUE_POSITIVE</c></tag> @@ -786,21 +905,76 @@ typedef enum { </item> </taglist> </item> + <tag><marker id="ErlNifHash"/><c>ErlNifHash</c></tag> + <item> + <p>An enumeration of the supported hash types that can be generated + using <seealso marker="#enif_hash"><c>enif_hash</c></seealso>. + </p> + <taglist> + <tag><c>ERL_NIF_INTERNAL_HASH</c></tag> + <item> + <p>Non-portable hash function that only guarantees the same hash + for the same term within one Erlang VM instance.</p> + <p>It takes 32-bit salt values and generates hashes within <c>0..2^32-1</c>.</p> + </item> + <tag><c>ERL_NIF_PHASH2</c></tag> + <item> + <p>Portable hash function that gives the same hash for the + same Erlang term regardless of machine architecture and ERTS version.</p> + <p><em>It ignores salt values</em> and generates hashes within <c>0..2^27-1</c>.</p> + <p>Slower than <c>ERL_NIF_INTERNAL_HASH.</c> + It corresponds to <seealso marker="erlang#phash2-1"><c>erlang:phash2/1</c></seealso>. + </p> + </item> + </taglist> + </item> + <tag><marker id="SysIOVec"/><c>SysIOVec</c></tag> + <item> + <p>A system I/O vector, as used by <c>writev</c> on + Unix and <c>WSASend</c> on Win32. It is used in + <c>ErlNifIOVec</c> and by + <seealso marker="#enif_ioq_peek"><c>enif_ioq_peek</c></seealso>.</p> + </item> + <tag><marker id="ErlNifIOVec"/><c>ErlNifIOVec</c></tag> + <item> + <code type="none"> +typedef struct { + int iovcnt; + size_t size; + SysIOVec* iov; +} ErlNifIOVec;</code> + <p>An I/O vector containing <c>iovcnt</c> <c>SysIOVec</c>s + pointing to the data. It is used by + <seealso marker="#enif_inspect_iovec"> + <c>enif_inspect_iovec</c></seealso> and + <seealso marker="#enif_ioq_enqv"> + <c>enif_ioq_enqv</c></seealso>.</p> + </item> + <tag><marker id="ErlNifIOQueueOpts"/><c>ErlNifIOQueueOpts</c></tag> + <item> + Options to configure a <c>ErlNifIOQueue</c>. + <taglist> + <tag>ERL_NIF_IOQ_NORMAL</tag> + <item><p>Create a normal I/O Queue</p></item> + </taglist> + </item> </taglist> </section> <funcs> <func> - <name><ret>void *</ret><nametext>enif_alloc(size_t size)</nametext></name> + <name since=""><ret>void *</ret><nametext>enif_alloc(size_t size)</nametext></name> <fsummary>Allocate dynamic memory.</fsummary> <desc> <p>Allocates memory of <c>size</c> bytes.</p> <p>Returns <c>NULL</c> if the allocation fails.</p> + <p>The returned pointer is suitably aligned for any built-in type that + fit in the allocated memory.</p> </desc> </func> <func> - <name><ret>int</ret> + <name since=""><ret>int</ret> <nametext>enif_alloc_binary(size_t size, ErlNifBinary* bin)</nametext> </name> <fsummary>Create a new binary.</fsummary> @@ -814,16 +988,20 @@ typedef enum { <seealso marker="#enif_make_binary"><c>enif_make_binary</c></seealso>. An allocated (and owned) <c>ErlNifBinary</c> can be kept between NIF calls.</p> + <p>If you do not need to reallocate or keep the data alive across NIF + calls, consider using <seealso marker="#enif_make_new_binary"> + <c>enif_make_new_binary</c></seealso> instead as it will allocate + small binaries on the process heap when possible.</p> <p>Returns <c>true</c> on success, or <c>false</c> if allocation fails.</p> </desc> </func> <func> - <name><ret>ErlNifEnv *</ret><nametext>enif_alloc_env()</nametext></name> + <name since="OTP R14B"><ret>ErlNifEnv *</ret><nametext>enif_alloc_env()</nametext></name> <fsummary>Create a new environment.</fsummary> <desc> - <p>Allocates a new process-independent environment. The environment can + <p>Allocates a new process independent environment. The environment can be used to hold terms that are not bound to any process. Such terms can later be copied to a process environment with <seealso marker="#enif_make_copy"><c>enif_make_copy</c></seealso> or @@ -834,7 +1012,7 @@ typedef enum { </func> <func> - <name><ret>void *</ret><nametext>enif_alloc_resource(ErlNifResourceType* + <name since="OTP R13B04"><ret>void *</ret><nametext>enif_alloc_resource(ErlNifResourceType* type, unsigned size)</nametext></name> <fsummary>Allocate a memory-managed resource object.</fsummary> <desc> @@ -844,7 +1022,7 @@ typedef enum { </func> <func> - <name><ret>size_t</ret><nametext>enif_binary_to_term(ErlNifEnv *env, + <name since="OTP 19.0"><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> @@ -869,7 +1047,7 @@ typedef enum { </func> <func> - <name><ret>void</ret><nametext>enif_clear_env(ErlNifEnv* env)</nametext> + <name since="OTP R14B"><ret>void</ret><nametext>enif_clear_env(ErlNifEnv* env)</nametext> </name> <fsummary>Clear an environment for reuse.</fsummary> <desc> @@ -880,7 +1058,7 @@ typedef enum { </func> <func> - <name><ret>int</ret> + <name since="OTP R13B04"><ret>int</ret> <nametext>enif_compare(ERL_NIF_TERM lhs, ERL_NIF_TERM rhs)</nametext> </name> <fsummary>Compare two terms.</fsummary> @@ -895,7 +1073,22 @@ typedef enum { </func> <func> - <name><ret>void</ret> + <name since="OTP 20.0"><ret>int</ret><nametext>enif_compare_monitors(const ErlNifMonitor + *monitor1, const ErlNifMonitor *monitor2)</nametext></name> + <fsummary>Compare two monitors.</fsummary> + <desc> + <marker id="enif_compare_monitors"></marker> + <p>Compares two <seealso marker="#ErlNifMonitor"><c>ErlNifMonitor</c></seealso>s. + Can also be used to imply some artificial order on monitors, + for whatever reason.</p> + <p>Returns <c>0</c> if <c>monitor1</c> and <c>monitor2</c> are equal, + < <c>0</c> if <c>monitor1</c> < <c>monitor2</c>, and + > <c>0</c> if <c>monitor1</c> > <c>monitor2</c>.</p> + </desc> + </func> + + <func> + <name since="OTP R13B04"><ret>void</ret> <nametext>enif_cond_broadcast(ErlNifCond *cnd)</nametext></name> <fsummary></fsummary> <desc> @@ -905,7 +1098,7 @@ typedef enum { </func> <func> - <name><ret>ErlNifCond *</ret> + <name since="OTP R13B04"><ret>ErlNifCond *</ret> <nametext>enif_cond_create(char *name)</nametext></name> <fsummary></fsummary> <desc> @@ -915,7 +1108,7 @@ typedef enum { </func> <func> - <name><ret>void</ret> + <name since="OTP R13B04"><ret>void</ret> <nametext>enif_cond_destroy(ErlNifCond *cnd)</nametext></name> <fsummary></fsummary> <desc> @@ -925,7 +1118,17 @@ typedef enum { </func> <func> - <name><ret>void</ret> + <name since="OTP 21.0"><ret>char*</ret> + <nametext>enif_cond_name(ErlNifCond* cnd)</nametext></name> + <fsummary></fsummary> + <desc> + <p>Same as <seealso marker="erl_driver#erl_drv_cond_name"> + <c>erl_drv_cond_name</c></seealso>.</p> + </desc> + </func> + + <func> + <name since="OTP R13B04"><ret>void</ret> <nametext>enif_cond_signal(ErlNifCond *cnd)</nametext></name> <fsummary></fsummary> <desc> @@ -935,7 +1138,7 @@ typedef enum { </func> <func> - <name><ret>void</ret> + <name since="OTP R13B04"><ret>void</ret> <nametext>enif_cond_wait(ErlNifCond *cnd, ErlNifMutex *mtx)</nametext> </name> <fsummary></fsummary> @@ -946,7 +1149,7 @@ typedef enum { </func> <func> - <name><ret>int</ret> + <name since="OTP R16B"><ret>int</ret> <nametext>enif_consume_timeslice(ErlNifEnv *env, int percent)</nametext> </name> <fsummary></fsummary> @@ -981,7 +1184,7 @@ typedef enum { </func> <func> - <name><ret>ErlNifTime</ret><nametext>enif_convert_time_unit(ErlNifTime + <name since="OTP 18.3"><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> @@ -1006,7 +1209,7 @@ typedef enum { </func> <func> - <name><ret>ERL_NIF_TERM</ret> + <name since="OTP 19.0"><ret>ERL_NIF_TERM</ret> <nametext>enif_cpu_time(ErlNifEnv *)</nametext></name> <fsummary></fsummary> <desc> @@ -1022,7 +1225,34 @@ typedef enum { </func> <func> - <name><ret>int</ret> + <name since="OTP 20.0"><ret>int</ret><nametext>enif_demonitor_process(ErlNifEnv* caller_env, + void* obj, const ErlNifMonitor* mon)</nametext></name> + <fsummary>Cancel a process monitor.</fsummary> + <desc> + <marker id="enif_demonitor_process"></marker> + <p>Cancels a monitor created earlier with <seealso marker="#enif_monitor_process"> + <c>enif_monitor_process</c></seealso>. Argument <c>obj</c> is a pointer + to the resource holding the monitor and <c>*mon</c> identifies the + monitor.</p> + <p>Argument <c>caller_env</c> is the environment of the calling process + or callback. Must only be NULL if calling from a custom thread.</p> + <p>Returns <c>0</c> if the monitor was successfully identified and removed. + Returns a non-zero value if the monitor could not be identified, which means + it was either</p> + <list type="bulleted"> + <item>never created for this resource</item> + <item>already cancelled</item> + <item>already triggered</item> + <item>just about to be triggered by a concurrent thread</item> + </list> + <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 since="OTP R13B04"><ret>int</ret> <nametext>enif_equal_tids(ErlNifTid tid1, ErlNifTid tid2)</nametext> </name> <fsummary></fsummary> @@ -1033,7 +1263,20 @@ typedef enum { </func> <func> - <name><ret>void</ret><nametext>enif_free(void* ptr)</nametext></name> + <name since="OTP 21.0"><ret>int</ret><nametext>enif_fprintf(FILE *stream, const char *format, ...)</nametext></name> + <fsummary>Format strings and Erlang terms.</fsummary> + <desc> + <p>Similar to <c>fprintf</c> but this format string also accepts + <c>"%T"</c>, which formats Erlang terms of type + <seealso marker="#ERL_NIF_TERM"><c>ERL_NIF_TERM</c></seealso>.</p> + <p>This function is primarily intended for debugging purpose. It is not + recommended to print very large terms with <c>%T</c>. The function may + change <c>errno</c>, even if successful.</p> + </desc> + </func> + + <func> + <name since=""><ret>void</ret><nametext>enif_free(void* ptr)</nametext></name> <fsummary>Free dynamic memory.</fsummary> <desc> <p>Frees memory allocated by @@ -1042,7 +1285,7 @@ typedef enum { </func> <func> - <name><ret>void</ret> + <name since="OTP R14B"><ret>void</ret> <nametext>enif_free_env(ErlNifEnv* env)</nametext></name> <fsummary>Free an environment allocated with enif_alloc_env.</fsummary> <desc> @@ -1053,7 +1296,32 @@ typedef enum { </func> <func> - <name><ret>int</ret><nametext>enif_get_atom(ErlNifEnv* env, ERL_NIF_TERM + <name since="OTP 20.1"><ret>void</ret> + <nametext>enif_free_iovec(ErlNifIOvec* iov)</nametext></name> + <fsummary>Free an ErlIOVec</fsummary> + <desc> + <p>Frees an io vector returned from + <seealso marker="#enif_inspect_iovec"> + <c>enif_inspect_iovec</c></seealso>. + This is needed only if a <c>NULL</c> environment is passed to + <seealso marker="#enif_inspect_iovec"> + <c>enif_inspect_iovec</c></seealso>.</p> + <code type="none"><![CDATA[ +ErlNifIOVec *iovec = NULL; +size_t max_elements = 128; +ERL_NIF_TERM tail; +if (!enif_inspect_iovec(NULL, max_elements, term, &tail, &iovec)) + return 0; + +// Do things with the iovec + +/* Free the iovector, possibly in another thread or nif function call */ +enif_free_iovec(iovec);]]></code> + </desc> + </func> + + <func> + <name since="OTP R13B04"><ret>int</ret><nametext>enif_get_atom(ErlNifEnv* env, ERL_NIF_TERM term, char* buf, unsigned size, ErlNifCharEncoding encode)</nametext> </name> <fsummary>Get the text representation of an atom term.</fsummary> @@ -1069,7 +1337,7 @@ typedef enum { </func> <func> - <name><ret>int</ret><nametext>enif_get_atom_length(ErlNifEnv* env, + <name since="OTP R14B"><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> @@ -1083,7 +1351,7 @@ typedef enum { </func> <func> - <name><ret>int</ret><nametext>enif_get_double(ErlNifEnv* env, + <name since="OTP R13B04"><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> <desc> @@ -1094,7 +1362,7 @@ typedef enum { </func> <func> - <name><ret>int</ret><nametext>enif_get_int(ErlNifEnv* env, ERL_NIF_TERM + <name since=""><ret>int</ret><nametext>enif_get_int(ErlNifEnv* env, ERL_NIF_TERM term, int* ip)</nametext></name> <fsummary>Read an integer term.</fsummary> <desc> @@ -1105,7 +1373,7 @@ typedef enum { </func> <func> - <name><ret>int</ret><nametext>enif_get_int64(ErlNifEnv* env, ERL_NIF_TERM + <name since="OTP R14B"><ret>int</ret><nametext>enif_get_int64(ErlNifEnv* env, ERL_NIF_TERM term, ErlNifSInt64* ip)</nametext></name> <fsummary>Read a 64-bit integer term.</fsummary> <desc> @@ -1116,7 +1384,7 @@ typedef enum { </func> <func> - <name><ret>int</ret><nametext>enif_get_local_pid(ErlNifEnv* env, + <name since="OTP R14B"><ret>int</ret><nametext>enif_get_local_pid(ErlNifEnv* env, ERL_NIF_TERM term, ErlNifPid* pid)</nametext></name> <fsummary>Read a local pid term.</fsummary> <desc> @@ -1128,7 +1396,7 @@ typedef enum { </func> <func> - <name><ret>int</ret><nametext>enif_get_local_port(ErlNifEnv* env, + <name since="OTP 19.0"><ret>int</ret><nametext>enif_get_local_port(ErlNifEnv* env, ERL_NIF_TERM term, ErlNifPort* port_id)</nametext></name> <fsummary>Read a local port term.</fsummary> <desc> @@ -1140,7 +1408,7 @@ typedef enum { </func> <func> - <name><ret>int</ret><nametext>enif_get_list_cell(ErlNifEnv* env, + <name since=""><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> @@ -1152,7 +1420,7 @@ typedef enum { </func> <func> - <name><ret>int</ret><nametext>enif_get_list_length(ErlNifEnv* env, + <name since="OTP R14B"><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> <desc> @@ -1163,7 +1431,7 @@ typedef enum { </func> <func> - <name><ret>int</ret><nametext>enif_get_long(ErlNifEnv* env, ERL_NIF_TERM + <name since="OTP R13B04"><ret>int</ret><nametext>enif_get_long(ErlNifEnv* env, ERL_NIF_TERM term, long int* ip)</nametext></name> <fsummary>Read a long integer term.</fsummary> <desc> @@ -1174,7 +1442,7 @@ typedef enum { </func> <func> - <name><ret>int</ret><nametext>enif_get_map_size(ErlNifEnv* env, + <name since="OTP 18.0"><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> @@ -1186,7 +1454,7 @@ typedef enum { </func> <func> - <name><ret>int</ret><nametext>enif_get_map_value(ErlNifEnv* env, + <name since="OTP 18.0"><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> @@ -1199,7 +1467,7 @@ typedef enum { </func> <func> - <name><ret>int</ret><nametext>enif_get_resource(ErlNifEnv* env, + <name since="OTP R13B04"><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> @@ -1212,7 +1480,7 @@ typedef enum { </func> <func> - <name><ret>int</ret><nametext>enif_get_string(ErlNifEnv* env, + <name since="OTP R13B04"><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> @@ -1236,7 +1504,7 @@ typedef enum { </func> <func> - <name><ret>int</ret><nametext>enif_get_tuple(ErlNifEnv* env, ERL_NIF_TERM + <name since="OTP R13B04"><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> <desc> @@ -1252,7 +1520,7 @@ typedef enum { </func> <func> - <name><ret>int</ret><nametext>enif_get_uint(ErlNifEnv* env, ERL_NIF_TERM + <name since="OTP R13B04"><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> <desc> @@ -1264,7 +1532,7 @@ typedef enum { </func> <func> - <name><ret>int</ret><nametext>enif_get_uint64(ErlNifEnv* env, + <name since="OTP R14B"><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> <desc> @@ -1276,7 +1544,7 @@ typedef enum { </func> <func> - <name><ret>int</ret><nametext>enif_get_ulong(ErlNifEnv* env, ERL_NIF_TERM + <name since=""><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> <desc> @@ -1289,7 +1557,7 @@ typedef enum { </func> <func> - <name><ret>int</ret><nametext>enif_getenv(const char* key, char* value, + <name since="OTP 18.2"><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> @@ -1299,20 +1567,19 @@ typedef enum { </func> <func> - <name><ret>int</ret><nametext>enif_has_pending_exception(ErlNifEnv* env, + <name since="OTP 18.0"><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>Returns <c>true</c> if a pending exception is associated with the environment <c>env</c>. If <c>reason</c> is a <c>NULL</c> pointer, ignore it. Otherwise, if a pending exception associated with - <c>env</c> exists, set <c>ERL_NIF_TERM</c> to which <c>reason</c> - points to the value of the exception's term. For example, if - <seealso marker="#enif_make_badarg"> + <c>env</c> exists, set <c>*reason</c> to the value of the exception + term. For example, if <seealso marker="#enif_make_badarg"> <c>enif_make_badarg</c></seealso> is called to set a pending <c>badarg</c> exception, a later call to <c>enif_has_pending_exception(env, &reason)</c> sets - <c>reason</c> to the atom <c>badarg</c>, then return <c>true</c>.</p> + <c>*reason</c> to the atom <c>badarg</c>, then return <c>true</c>.</p> <p>See also <seealso marker="#enif_make_badarg"> <c>enif_make_badarg</c></seealso> and <seealso marker="#enif_raise_exception"> @@ -1321,7 +1588,20 @@ typedef enum { </func> <func> - <name><ret>int</ret><nametext>enif_inspect_binary(ErlNifEnv* env, + <name since="OTP 20.0"> + <ret>ErlNifUInt64</ret> + <nametext>enif_hash(ErlNifHash type, ERL_NIF_TERM term, ErlNifUInt64 salt)</nametext> + </name> + <fsummary>Hash terms.</fsummary> + <desc> + <p>Hashes <c>term</c> according to the specified + <seealso marker="#ErlNifHash"><c>ErlNifHash</c></seealso> <c>type</c>.</p> + <p>Ranges of taken salt (if any) and returned value depend on the hash type.</p> + </desc> + </func> + + <func> + <name since=""><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> @@ -1333,7 +1613,7 @@ typedef enum { </func> <func> - <name><ret>int</ret><nametext>enif_inspect_iolist_as_binary(ErlNifEnv* + <name since="OTP R13B04"><ret>int</ret><nametext>enif_inspect_iolist_as_binary(ErlNifEnv* env, ERL_NIF_TERM term, ErlNifBinary* bin)</nametext></name> <fsummary>Inspect the content of an iolist.</fsummary> <desc> @@ -1347,7 +1627,142 @@ typedef enum { </func> <func> - <name><ret>int</ret> + <name since="OTP 20.1"><ret>int</ret><nametext>enif_inspect_iovec(ErlNifEnv* + env, size_t max_elements, ERL_NIF_TERM iovec_term, ERL_NIF_TERM* tail, + ErlNifIOVec** iovec)</nametext></name> + <fsummary>Inspect a list of binaries as an ErlNifIOVec.</fsummary> + <desc> + <p>Fills <c>iovec</c> with the list of binaries provided in + <c>iovec_term</c>. The number of elements handled in the call is + limited to <c>max_elements</c>, and <c>tail</c> is set to the + remainder of the list. Note that the output may be longer than + <c>max_elements</c> on some platforms. + </p> + <p>To create a list of binaries from an arbitrary iolist, use + <seealso marker="erts:erlang#iolist_to_iovec/1"> + <c>erlang:iolist_to_iovec/1</c></seealso>.</p> + <p>When calling this function, <c>iovec</c> should contain a pointer to + <c>NULL</c> or a ErlNifIOVec structure that should be used if + possible. e.g. + </p> + <code type="none"> +/* Don't use a pre-allocated structure */ +ErlNifIOVec *iovec = NULL; +enif_inspect_iovec(env, max_elements, term, &tail, &iovec); + +/* Use a stack-allocated vector as an optimization for vectors with few elements */ +ErlNifIOVec vec, *iovec = &vec; +enif_inspect_iovec(env, max_elements, term, &tail, &iovec); +</code> + <p>The contents of the <c>iovec</c> is valid until the called nif + function returns. If the <c>iovec</c> should be valid after the nif + call returns, it is possible to call this function with a + <c>NULL</c> environment. If no environment is given the <c>iovec</c> + owns the data in the vector and it has to be explicitly freed using + <seealso marker="#enif_free_iovec"><c>enif_free_iovec</c> + </seealso>.</p> + <p>Returns <c>true</c> on success, or <c>false</c> if <c>iovec_term</c> + not an iovec.</p> + </desc> + </func> + + <func> + <name since="OTP 20.1"><ret>ErlNifIOQueue *</ret> + <nametext>enif_ioq_create(ErlNifIOQueueOpts opts)</nametext></name> + <fsummary>Create a new IO Queue</fsummary> + <desc> + <p>Create a new I/O Queue that can be used to store data. + <c>opts</c> has to be set to <c>ERL_NIF_IOQ_NORMAL</c>. + </p> + </desc> + </func> + + <func> + <name since="OTP 20.1"><ret>void</ret> + <nametext>enif_ioq_destroy(ErlNifIOQueue *q)</nametext></name> + <fsummary>Destroy an IO Queue and free it's content</fsummary> + <desc> + <p>Destroy the I/O queue and free all of it's contents</p> + </desc> + </func> + + <func> + <name since="OTP 20.1"><ret>int</ret> + <nametext>enif_ioq_deq(ErlNifIOQueue *q, size_t count, size_t *size)</nametext></name> + <fsummary>Dequeue count bytes from the IO Queue</fsummary> + <desc> + <p>Dequeue <c>count</c> bytes from the I/O queue. + If <c>size</c> is not <c>NULL</c>, the new size of the queue + is placed there.</p> + <p>Returns <c>true</c> on success, or <c>false</c> if the I/O does + not contain <c>count</c> bytes. On failure the queue is left un-altered.</p> + </desc> + </func> + + <func> + <name since="OTP 20.1"><ret>int</ret> + <nametext>enif_ioq_enq_binary(ErlNifIOQueue *q, ErlNifBinary *bin, size_t skip)</nametext></name> + <fsummary>Enqueue the binary into the IO Queue</fsummary> + <desc> + <p>Enqueue the <c>bin</c> into <c>q</c> skipping the first <c>skip</c> bytes.</p> + <p>Returns <c>true</c> on success, or <c>false</c> if <c>skip</c> is greater + than the size of <c>bin</c>. Any ownership of the binary data is transferred + to the queue and <c>bin</c> is to be considered read-only for the rest of the NIF + call and then as released.</p> + </desc> + </func> + + <func> + <name since="OTP 20.1"><ret>int</ret> + <nametext>enif_ioq_enqv(ErlNifIOQueue *q, ErlNifIOVec *iovec, size_t skip)</nametext></name> + <fsummary>Enqueue the iovec into the IO Queue</fsummary> + <desc> + <p>Enqueue the <c>iovec</c> into <c>q</c> skipping the first <c>skip</c> bytes.</p> + <p>Returns <c>true</c> on success, or <c>false</c> if <c>skip</c> is greater + than the size of <c>iovec</c>.</p> + </desc> + </func> + + <func> + <name since="OTP 20.1"><ret>SysIOVec *</ret> + <nametext>enif_ioq_peek(ErlNifIOQueue *q, int *iovlen)</nametext></name> + <fsummary>Peek inside the IO Queue</fsummary> + <desc> + <p>Get the I/O queue as a pointer to an array of <c>SysIOVec</c>s. + It also returns the number of elements in <c>iovlen</c>.</p> + <p>Nothing is removed from the queue by this function, that must be done + with <seealso marker="#enif_ioq_deq"><c>enif_ioq_deq</c></seealso>.</p> + <p>The returned array is suitable to use with the Unix system + call <c>writev</c>.</p> + </desc> + </func> + + <func> + <name since="OTP 21.0"><ret>int</ret> + <nametext>enif_ioq_peek_head(ErlNifEnv *env, ErlNifIOQueue *q, size_t *size, ERL_NIF_TERM *bin_term)</nametext></name> + <fsummary>Peek the head of the IO Queue.</fsummary> + <desc> + <p>Get the head of the IO Queue as a binary term.</p> + <p>If <c>size</c> is not <c>NULL</c>, the size of the head is placed + there.</p> + <p>Nothing is removed from the queue by this function, that must be done + with <seealso marker="#enif_ioq_deq"><c>enif_ioq_deq</c></seealso>.</p> + <p>Returns <c>true</c> on success, or <c>false</c> if the queue is + empty.</p> + </desc> + </func> + + <func> + <name since="OTP 20.1"><ret>size_t</ret> + <nametext>enif_ioq_size(ErlNifIOQueue *q)</nametext></name> + <fsummary>Get the current size of the IO Queue</fsummary> + <desc> + <p>Get the size of <c>q</c>.</p> + </desc> + </func> + + <func> + <name since="OTP R13B04"><ret>int</ret> <nametext>enif_is_atom(ErlNifEnv* env, ERL_NIF_TERM term)</nametext> </name> <fsummary>Determine if a term is an atom.</fsummary> @@ -1357,7 +1772,7 @@ typedef enum { </func> <func> - <name><ret>int</ret> + <name since=""><ret>int</ret> <nametext>enif_is_binary(ErlNifEnv* env, ERL_NIF_TERM term)</nametext> </name> <fsummary>Determine if a term is a binary.</fsummary> @@ -1367,7 +1782,7 @@ typedef enum { </func> <func> - <name><ret>int</ret> + <name since="OTP 19.0"><ret>int</ret> <nametext>enif_is_current_process_alive(ErlNifEnv* env)</nametext> </name> <fsummary>Determine if currently executing process is alive.</fsummary> @@ -1380,7 +1795,7 @@ typedef enum { </func> <func> - <name><ret>int</ret><nametext>enif_is_empty_list(ErlNifEnv* env, + <name since="OTP R13B04"><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> @@ -1389,7 +1804,7 @@ typedef enum { </func> <func> - <name><ret>int</ret><nametext>enif_is_exception(ErlNifEnv* env, + <name since="OTP R14B03"><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><marker id="enif_is_exception"/> @@ -1398,7 +1813,7 @@ typedef enum { </func> <func> - <name><ret>int</ret><nametext>enif_is_fun(ErlNifEnv* env, ERL_NIF_TERM + <name since="OTP R13B04"><ret>int</ret><nametext>enif_is_fun(ErlNifEnv* env, ERL_NIF_TERM term)</nametext></name> <fsummary>Determine if a term is a fun.</fsummary> <desc> @@ -1407,7 +1822,7 @@ typedef enum { </func> <func> - <name><ret>int</ret><nametext>enif_is_identical(ERL_NIF_TERM lhs, + <name since="OTP R13B04"><ret>int</ret><nametext>enif_is_identical(ERL_NIF_TERM lhs, ERL_NIF_TERM rhs)</nametext></name> <fsummary>Erlang operator =:=.</fsummary> <desc> @@ -1417,7 +1832,7 @@ typedef enum { </func> <func> - <name><ret>int</ret> + <name since="OTP R14B"><ret>int</ret> <nametext>enif_is_list(ErlNifEnv* env, ERL_NIF_TERM term)</nametext> </name> <fsummary>Determine if a term is a list.</fsummary> @@ -1427,7 +1842,7 @@ typedef enum { </func> <func> - <name><ret>int</ret><nametext>enif_is_map(ErlNifEnv* env, ERL_NIF_TERM + <name since="OTP 18.0"><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> @@ -1437,7 +1852,7 @@ typedef enum { </func> <func> - <name><ret>int</ret><nametext>enif_is_number(ErlNifEnv* env, ERL_NIF_TERM + <name since="OTP R15B"><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> <desc> @@ -1446,7 +1861,7 @@ typedef enum { </func> <func> - <name><ret>int</ret> + <name since="OTP R13B04"><ret>int</ret> <nametext>enif_is_pid(ErlNifEnv* env, ERL_NIF_TERM term)</nametext> </name> <fsummary>Determine if a term is a pid.</fsummary> @@ -1456,7 +1871,7 @@ typedef enum { </func> <func> - <name><ret>int</ret> + <name since="OTP R13B04"><ret>int</ret> <nametext>enif_is_port(ErlNifEnv* env, ERL_NIF_TERM term)</nametext> </name> <fsummary>Determine if a term is a port.</fsummary> @@ -1466,7 +1881,7 @@ typedef enum { </func> <func> - <name><ret>int</ret><nametext>enif_is_port_alive(ErlNifEnv* env, + <name since="OTP 19.0"><ret>int</ret><nametext>enif_is_port_alive(ErlNifEnv* env, ErlNifPort *port_id)</nametext></name> <fsummary>Determine if a local port is alive.</fsummary> <desc> @@ -1478,7 +1893,7 @@ typedef enum { </func> <func> - <name><ret>int</ret><nametext>enif_is_process_alive(ErlNifEnv* env, + <name since="OTP 19.0"><ret>int</ret><nametext>enif_is_process_alive(ErlNifEnv* env, ErlNifPid *pid)</nametext></name> <fsummary>Determine if a local process is alive.</fsummary> <desc> @@ -1490,7 +1905,7 @@ typedef enum { </func> <func> - <name><ret>int</ret> + <name since="OTP R13B04"><ret>int</ret> <nametext>enif_is_ref(ErlNifEnv* env, ERL_NIF_TERM term)</nametext> </name> <fsummary>Determine if a term is a reference.</fsummary> @@ -1500,7 +1915,7 @@ typedef enum { </func> <func> - <name><ret>int</ret> + <name since="OTP R14B"><ret>int</ret> <nametext>enif_is_tuple(ErlNifEnv* env, ERL_NIF_TERM term)</nametext> </name> <fsummary>Determine if a term is a tuple.</fsummary> @@ -1510,7 +1925,7 @@ typedef enum { </func> <func> - <name><ret>int</ret> + <name since="OTP R14B"><ret>int</ret> <nametext>enif_keep_resource(void* obj)</nametext> </name> <fsummary>Add a reference to a resource object.</fsummary> @@ -1526,7 +1941,7 @@ typedef enum { </func> <func> - <name><ret>ERL_NIF_TERM</ret> + <name since=""><ret>ERL_NIF_TERM</ret> <nametext>enif_make_atom(ErlNifEnv* env, const char* name)</nametext> </name> <fsummary>Create an atom term.</fsummary> @@ -1540,7 +1955,7 @@ typedef enum { </func> <func> - <name><ret>ERL_NIF_TERM</ret><nametext>enif_make_atom_len(ErlNifEnv* env, + <name since="OTP R14B"><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> @@ -1554,7 +1969,7 @@ typedef enum { </func> <func> - <name><ret>ERL_NIF_TERM</ret> + <name since=""><ret>ERL_NIF_TERM</ret> <nametext>enif_make_badarg(ErlNifEnv* env)</nametext></name> <fsummary>Make a badarg exception.</fsummary> <desc> @@ -1582,7 +1997,7 @@ typedef enum { </func> <func> - <name><ret>ERL_NIF_TERM</ret> + <name since=""><ret>ERL_NIF_TERM</ret> <nametext>enif_make_binary(ErlNifEnv* env, ErlNifBinary* bin)</nametext> </name> <fsummary>Make a binary term.</fsummary> @@ -1595,7 +2010,7 @@ typedef enum { </func> <func> - <name><ret>ERL_NIF_TERM</ret><nametext>enif_make_copy(ErlNifEnv* dst_env, + <name since="OTP R14B"><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> <desc> @@ -1606,7 +2021,7 @@ typedef enum { </func> <func> - <name><ret>ERL_NIF_TERM</ret> + <name since="OTP R13B04"><ret>ERL_NIF_TERM</ret> <nametext>enif_make_double(ErlNifEnv* env, double d)</nametext></name> <fsummary>Create a floating-point term.</fsummary> <desc> @@ -1618,7 +2033,7 @@ typedef enum { </func> <func> - <name><ret>int</ret><nametext>enif_make_existing_atom(ErlNifEnv* env, + <name since="OTP R13B04"><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> @@ -1634,7 +2049,7 @@ typedef enum { </func> <func> - <name><ret>int</ret><nametext>enif_make_existing_atom_len(ErlNifEnv* env, + <name since="OTP R14B"><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> @@ -1650,7 +2065,7 @@ typedef enum { </desc> </func> - <func><name><ret>ERL_NIF_TERM</ret> + <func><name since=""><ret>ERL_NIF_TERM</ret> <nametext>enif_make_int(ErlNifEnv* env, int i)</nametext></name> <fsummary>Create an integer term.</fsummary> <desc> @@ -1659,7 +2074,7 @@ typedef enum { </func> <func> - <name><ret>ERL_NIF_TERM</ret> + <name since="OTP R14B"><ret>ERL_NIF_TERM</ret> <nametext>enif_make_int64(ErlNifEnv* env, ErlNifSInt64 i)</nametext> </name> <fsummary>Create an integer term.</fsummary> @@ -1669,7 +2084,7 @@ typedef enum { </func> <func> - <name><ret>ERL_NIF_TERM</ret> + <name since=""><ret>ERL_NIF_TERM</ret> <nametext>enif_make_list(ErlNifEnv* env, unsigned cnt, ...)</nametext> </name> <fsummary>Create a list term.</fsummary> @@ -1682,24 +2097,24 @@ typedef enum { </func> <func> - <name><ret>ERL_NIF_TERM</ret> + <name since="OTP R13B04"><ret>ERL_NIF_TERM</ret> <nametext>enif_make_list1(ErlNifEnv* env, ERL_NIF_TERM e1)</nametext> </name> - <name><ret>ERL_NIF_TERM</ret><nametext>enif_make_list2(ErlNifEnv* env, + <name since="OTP R13B04"><ret>ERL_NIF_TERM</ret><nametext>enif_make_list2(ErlNifEnv* env, ERL_NIF_TERM e1, ERL_NIF_TERM e2)</nametext></name> - <name><ret>ERL_NIF_TERM</ret><nametext>enif_make_list3(ErlNifEnv* env, + <name since="OTP R13B04"><ret>ERL_NIF_TERM</ret><nametext>enif_make_list3(ErlNifEnv* env, ERL_NIF_TERM e1, ERL_NIF_TERM e2, ERL_NIF_TERM e3)</nametext></name> - <name><ret>ERL_NIF_TERM</ret><nametext>enif_make_list4(ErlNifEnv* env, + <name since="OTP R13B04"><ret>ERL_NIF_TERM</ret><nametext>enif_make_list4(ErlNifEnv* env, ERL_NIF_TERM e1, ..., ERL_NIF_TERM e4)</nametext></name> - <name><ret>ERL_NIF_TERM</ret><nametext>enif_make_list5(ErlNifEnv* env, + <name since="OTP R13B04"><ret>ERL_NIF_TERM</ret><nametext>enif_make_list5(ErlNifEnv* env, ERL_NIF_TERM e1, ..., ERL_NIF_TERM e5)</nametext></name> - <name><ret>ERL_NIF_TERM</ret><nametext>enif_make_list6(ErlNifEnv* env, + <name since="OTP R13B04"><ret>ERL_NIF_TERM</ret><nametext>enif_make_list6(ErlNifEnv* env, ERL_NIF_TERM e1, ..., ERL_NIF_TERM e6)</nametext></name> - <name><ret>ERL_NIF_TERM</ret><nametext>enif_make_list7(ErlNifEnv* env, + <name since="OTP R13B04"><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, + <name since="OTP R13B04"><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, + <name since="OTP R13B04"><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> <desc> @@ -1711,7 +2126,7 @@ typedef enum { </func> <func> - <name><ret>ERL_NIF_TERM</ret><nametext>enif_make_list_cell(ErlNifEnv* + <name since=""><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> <desc> @@ -1720,7 +2135,7 @@ typedef enum { </func> <func> - <name><ret>ERL_NIF_TERM</ret> + <name since="OTP R13B04"><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> @@ -1732,7 +2147,7 @@ typedef enum { </func> <func> - <name><ret>ERL_NIF_TERM</ret> + <name since="OTP R13B04"><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> @@ -1741,7 +2156,7 @@ typedef enum { </func> <func> - <name><ret>int</ret><nametext>enif_make_map_put(ErlNifEnv* env, + <name since="OTP 18.0"><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> @@ -1757,7 +2172,7 @@ typedef enum { </func> <func> - <name><ret>int</ret><nametext>enif_make_map_remove(ErlNifEnv* env, + <name since="OTP 18.0"><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> @@ -1773,7 +2188,7 @@ typedef enum { </func> <func> - <name><ret>int</ret><nametext>enif_make_map_update(ErlNifEnv* env, + <name since="OTP 18.0"><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> @@ -1788,7 +2203,21 @@ typedef enum { </func> <func> - <name><ret>unsigned char *</ret><nametext>enif_make_new_binary(ErlNifEnv* + <name since="OTP 21.0"><ret>int</ret> + <nametext>enif_make_map_from_arrays(ErlNifEnv* env, ERL_NIF_TERM keys[], + ERL_NIF_TERM values[], size_t cnt, ERL_NIF_TERM *map_out)</nametext></name> + <fsummary>Make map term from the given keys and values.</fsummary> + <desc> + <p>Makes a map term from the given keys and values.</p> + <p>If successful, this function sets <c>*map_out</c> to the new map and + returns <c>true</c>. Returns <c>false</c> there are any duplicate + keys.</p> + <p>All keys and values must belong to <c>env</c>.</p> + </desc> + </func> + + <func> + <name since="OTP R14B"><ret>unsigned char *</ret><nametext>enif_make_new_binary(ErlNifEnv* env, size_t size, ERL_NIF_TERM* termp)</nametext></name> <fsummary>Allocate and create a new binary term.</fsummary> <desc> @@ -1804,7 +2233,7 @@ typedef enum { </func> <func> - <name><ret>ERL_NIF_TERM</ret> + <name since="OTP 18.0"><ret>ERL_NIF_TERM</ret> <nametext>enif_make_new_map(ErlNifEnv* env)</nametext></name> <fsummary>Make an empty map term.</fsummary> <desc> @@ -1813,7 +2242,7 @@ typedef enum { </func> <func> - <name><ret>ERL_NIF_TERM</ret> + <name since="OTP R14B"><ret>ERL_NIF_TERM</ret> <nametext>enif_make_pid(ErlNifEnv* env, const ErlNifPid* pid)</nametext> </name> <fsummary>Make a pid term.</fsummary> @@ -1823,7 +2252,7 @@ typedef enum { </func> <func> - <name><ret>ERL_NIF_TERM</ret> + <name since="OTP R13B04"><ret>ERL_NIF_TERM</ret> <nametext>enif_make_ref(ErlNifEnv* env)</nametext></name> <fsummary>Create a reference.</fsummary> <desc> @@ -1833,7 +2262,7 @@ typedef enum { </func> <func> - <name><ret>ERL_NIF_TERM</ret> + <name since="OTP R13B04"><ret>ERL_NIF_TERM</ret> <nametext>enif_make_resource(ErlNifEnv* env, void* obj)</nametext> </name> <fsummary>Create an opaque handle to a resource object.</fsummary> @@ -1850,15 +2279,38 @@ typedef enum { details, see the <seealso marker="#enif_resource_example">example of creating and returning a resource object</seealso> in the User's Guide.</p> - <p>Notice that the only defined behavior of using a resource term in - an Erlang program is to store it and send it between processes on the - same node. Other operations, such as matching or - <c>term_to_binary</c>, have unpredictable (but harmless) results.</p> - </desc> - </func> - - <func> - <name><ret>ERL_NIF_TERM</ret> + <note> + <p>Since ERTS 9.0 (OTP-20.0), resource terms have a defined behavior + when compared and serialized through <c>term_to_binary</c> or passed + between nodes.</p> + <list type="bulleted"> + <item> + <p>Two resource terms will compare equal if and only if they + would yield the same resource object pointer when passed to + <seealso marker="#enif_get_resource"><c>enif_get_resource</c></seealso>.</p> + </item> + <item> + <p>A resource term can be serialized with <c>term_to_binary</c> and later + be fully recreated if the resource object is still alive when + <c>binary_to_term</c> is called. A <em>stale</em> resource term will be + returned from <c>binary_to_term</c> if the resource object has + been deallocated. <seealso marker="#enif_get_resource"><c>enif_get_resource</c></seealso> + will return false for stale resource terms.</p> + <p>The same principles of serialization apply when passing + resource terms in messages to remote nodes and back again. A + resource term will act stale on all nodes except the node where + its resource object is still alive in memory.</p> + </item> + </list> + <p>Before ERTS 9.0 (OTP-20.0), all resource terms did + compare equal to each other and to empty binaries (<c><<>></c>). + If serialized, they would be recreated as plain empty binaries.</p> + </note> + </desc> + </func> + + <func> + <name since="OTP R14B"><ret>ERL_NIF_TERM</ret> <nametext>enif_make_resource_binary(ErlNifEnv* env, void* obj, const void* data, size_t size)</nametext></name> <fsummary>Create a custom binary term.</fsummary> @@ -1884,7 +2336,7 @@ typedef enum { </func> <func> - <name><ret>int</ret> + <name since="OTP R15B"><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> @@ -1900,7 +2352,7 @@ typedef enum { </func> <func> - <name><ret>ERL_NIF_TERM</ret><nametext>enif_make_string(ErlNifEnv* env, + <name since=""><ret>ERL_NIF_TERM</ret><nametext>enif_make_string(ErlNifEnv* env, const char* string, ErlNifCharEncoding encoding)</nametext></name> <fsummary>Create a string.</fsummary> <desc> @@ -1911,7 +2363,7 @@ typedef enum { </func> <func> - <name><ret>ERL_NIF_TERM</ret><nametext>enif_make_string_len(ErlNifEnv* + <name since="OTP R14B"><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> @@ -1924,7 +2376,7 @@ typedef enum { </func> <func> - <name><ret>ERL_NIF_TERM</ret><nametext>enif_make_sub_binary(ErlNifEnv* + <name since="OTP R13B04"><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> <desc> @@ -1936,7 +2388,7 @@ typedef enum { </func> <func> - <name><ret>ERL_NIF_TERM</ret><nametext>enif_make_tuple(ErlNifEnv* env, + <name since=""><ret>ERL_NIF_TERM</ret><nametext>enif_make_tuple(ErlNifEnv* env, unsigned cnt, ...)</nametext></name> <fsummary>Creates a tuple term.</fsummary> <desc> @@ -1947,23 +2399,23 @@ typedef enum { </func> <func> - <name><ret>ERL_NIF_TERM</ret><nametext>enif_make_tuple1(ErlNifEnv* env, + <name since="OTP R13B04"><ret>ERL_NIF_TERM</ret><nametext>enif_make_tuple1(ErlNifEnv* env, ERL_NIF_TERM e1)</nametext></name> - <name><ret>ERL_NIF_TERM</ret><nametext>enif_make_tuple2(ErlNifEnv* env, + <name since="OTP R13B04"><ret>ERL_NIF_TERM</ret><nametext>enif_make_tuple2(ErlNifEnv* env, ERL_NIF_TERM e1, ERL_NIF_TERM e2)</nametext></name> - <name><ret>ERL_NIF_TERM</ret><nametext>enif_make_tuple3(ErlNifEnv* env, + <name since="OTP R13B04"><ret>ERL_NIF_TERM</ret><nametext>enif_make_tuple3(ErlNifEnv* env, ERL_NIF_TERM e1, ERL_NIF_TERM e2, ERL_NIF_TERM e3)</nametext></name> - <name><ret>ERL_NIF_TERM</ret><nametext>enif_make_tuple4(ErlNifEnv* env, + <name since="OTP R13B04"><ret>ERL_NIF_TERM</ret><nametext>enif_make_tuple4(ErlNifEnv* env, ERL_NIF_TERM e1, ..., ERL_NIF_TERM e4)</nametext></name> - <name><ret>ERL_NIF_TERM</ret><nametext>enif_make_tuple5(ErlNifEnv* env, + <name since="OTP R13B04"><ret>ERL_NIF_TERM</ret><nametext>enif_make_tuple5(ErlNifEnv* env, ERL_NIF_TERM e1, ..., ERL_NIF_TERM e5)</nametext></name> - <name><ret>ERL_NIF_TERM</ret><nametext>enif_make_tuple6(ErlNifEnv* env, + <name since="OTP R13B04"><ret>ERL_NIF_TERM</ret><nametext>enif_make_tuple6(ErlNifEnv* env, ERL_NIF_TERM e1, ..., ERL_NIF_TERM e6)</nametext></name> - <name><ret>ERL_NIF_TERM</ret><nametext>enif_make_tuple7(ErlNifEnv* env, + <name since="OTP R13B04"><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, + <name since="OTP R13B04"><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, + <name since="OTP R13B04"><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> <desc> @@ -1975,7 +2427,7 @@ typedef enum { </func> <func> - <name><ret>ERL_NIF_TERM</ret> + <name since="OTP R13B04"><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> @@ -1986,7 +2438,7 @@ typedef enum { </func> <func> - <name><ret>ERL_NIF_TERM</ret> + <name since="OTP R13B04"><ret>ERL_NIF_TERM</ret> <nametext>enif_make_uint(ErlNifEnv* env, unsigned int i)</nametext> </name> <fsummary>Create an unsigned integer term.</fsummary> @@ -1996,7 +2448,7 @@ typedef enum { </func> <func> - <name><ret>ERL_NIF_TERM</ret> + <name since="OTP R14B"><ret>ERL_NIF_TERM</ret> <nametext>enif_make_uint64(ErlNifEnv* env, ErlNifUInt64 i)</nametext> </name> <fsummary>Create an unsigned integer term.</fsummary> @@ -2006,7 +2458,7 @@ typedef enum { </func> <func> - <name><ret>ERL_NIF_TERM</ret> + <name since=""><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> @@ -2016,7 +2468,7 @@ typedef enum { </func> <func> - <name><ret>ERL_NIF_TERM</ret><nametext>enif_make_unique_integer(ErlNifEnv + <name since="OTP 19.0"><ret>ERL_NIF_TERM</ret><nametext>enif_make_unique_integer(ErlNifEnv *env, ErlNifUniqueInteger properties)</nametext></name> <fsummary></fsummary> <desc> @@ -2034,7 +2486,7 @@ typedef enum { </func> <func> - <name><ret>int</ret><nametext>enif_map_iterator_create(ErlNifEnv *env, + <name since="OTP 18.0"><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> @@ -2069,7 +2521,7 @@ enif_map_iterator_destroy(env, &iter);</code> </func> <func> - <name><ret>void</ret><nametext>enif_map_iterator_destroy(ErlNifEnv *env, + <name since="OTP 18.0"><ret>void</ret><nametext>enif_map_iterator_destroy(ErlNifEnv *env, ErlNifMapIterator *iter)</nametext></name> <fsummary>Destroy a map iterator.</fsummary> <desc> @@ -2080,7 +2532,7 @@ enif_map_iterator_destroy(env, &iter);</code> </func> <func> - <name><ret>int</ret><nametext>enif_map_iterator_get_pair(ErlNifEnv *env, + <name since="OTP 18.0"><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> @@ -2093,7 +2545,7 @@ enif_map_iterator_destroy(env, &iter);</code> </func> <func> - <name><ret>int</ret><nametext>enif_map_iterator_is_head(ErlNifEnv *env, + <name since="OTP 18.0"><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> @@ -2103,7 +2555,7 @@ enif_map_iterator_destroy(env, &iter);</code> </func> <func> - <name><ret>int</ret><nametext>enif_map_iterator_is_tail(ErlNifEnv *env, + <name since="OTP 18.0"><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> @@ -2113,7 +2565,7 @@ enif_map_iterator_destroy(env, &iter);</code> </func> <func> - <name><ret>int</ret><nametext>enif_map_iterator_next(ErlNifEnv *env, + <name since="OTP 18.0"><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> @@ -2125,7 +2577,7 @@ enif_map_iterator_destroy(env, &iter);</code> </func> <func> - <name><ret>int</ret><nametext>enif_map_iterator_prev(ErlNifEnv *env, + <name since="OTP 18.0"><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> @@ -2137,7 +2589,39 @@ enif_map_iterator_destroy(env, &iter);</code> </func> <func> - <name><ret>ErlNifTime</ret> + <name since="OTP 20.0"><ret>int</ret><nametext>enif_monitor_process(ErlNifEnv* caller_env, + void* obj, const ErlNifPid* target_pid, ErlNifMonitor* mon)</nametext></name> + <fsummary>Monitor a process from a resource.</fsummary> + <desc> + <marker id="enif_monitor_process"></marker> + <p>Starts monitoring a process from a resource. When a process is + monitored, a process exit results in a call to the provided + <seealso marker="#ErlNifResourceDown"> + <c>down</c></seealso> callback associated with the resource type.</p> + <p>Argument <c>obj</c> is pointer to the resource to hold the monitor and + <c>*target_pid</c> identifies the local process to be monitored.</p> + <p>If <c>mon</c> is not <c>NULL</c>, a successful call stores the + identity of the monitor in the + <seealso marker="#ErlNifMonitor"><c>ErlNifMonitor</c></seealso> + struct pointed to by <c>mon</c>. This identifier is used to refer to the + monitor for later removal with + <seealso marker="#enif_demonitor_process"><c>enif_demonitor_process</c></seealso> + or compare with + <seealso marker="#enif_compare_monitors"><c>enif_compare_monitors</c></seealso>. + A monitor is automatically removed when it triggers or when + the resource is deallocated.</p> + <p>Argument <c>caller_env</c> is the environment of the calling process + or callback. Must only be NULL if calling from a custom thread.</p> + <p>Returns <c>0</c> on success, < 0 if no <c>down</c> callback is + provided, and > 0 if the process is no longer 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 since="OTP 18.3"><ret>ErlNifTime</ret> <nametext>enif_monotonic_time(ErlNifTimeUnit time_unit)</nametext> </name> <fsummary>Get Erlang monotonic time.</fsummary> @@ -2158,7 +2642,7 @@ enif_map_iterator_destroy(env, &iter);</code> </func> <func> - <name><ret>ErlNifMutex *</ret> + <name since="OTP R13B04"><ret>ErlNifMutex *</ret> <nametext>enif_mutex_create(char *name)</nametext></name> <fsummary></fsummary> <desc> @@ -2168,7 +2652,7 @@ enif_map_iterator_destroy(env, &iter);</code> </func> <func> - <name><ret>void</ret> + <name since="OTP R13B04"><ret>void</ret> <nametext>enif_mutex_destroy(ErlNifMutex *mtx)</nametext></name> <fsummary></fsummary> <desc> @@ -2178,7 +2662,7 @@ enif_map_iterator_destroy(env, &iter);</code> </func> <func> - <name><ret>void</ret> + <name since="OTP R13B04"><ret>void</ret> <nametext>enif_mutex_lock(ErlNifMutex *mtx)</nametext></name> <fsummary></fsummary> <desc> @@ -2188,7 +2672,17 @@ enif_map_iterator_destroy(env, &iter);</code> </func> <func> - <name><ret>int</ret> + <name since="OTP 21.0"><ret>char*</ret> + <nametext>enif_mutex_name(ErlNifMutex* mtx)</nametext></name> + <fsummary></fsummary> + <desc> + <p>Same as <seealso marker="erl_driver#erl_drv_mutex_name"> + <c>erl_drv_mutex_name</c></seealso>.</p> + </desc> + </func> + + <func> + <name since="OTP R13B04"><ret>int</ret> <nametext>enif_mutex_trylock(ErlNifMutex *mtx)</nametext></name> <fsummary></fsummary> <desc> @@ -2198,7 +2692,7 @@ enif_map_iterator_destroy(env, &iter);</code> </func> <func> - <name><ret>void</ret> + <name since="OTP R13B04"><ret>void</ret> <nametext>enif_mutex_unlock(ErlNifMutex *mtx)</nametext></name> <fsummary></fsummary> <desc> @@ -2208,7 +2702,7 @@ enif_map_iterator_destroy(env, &iter);</code> </func> <func> - <name><ret>ERL_NIF_TERM</ret> + <name since="OTP 19.0"><ret>ERL_NIF_TERM</ret> <nametext>enif_now_time(ErlNifEnv *env)</nametext></name> <fsummary></fsummary> <desc> @@ -2219,7 +2713,7 @@ enif_map_iterator_destroy(env, &iter);</code> </func> <func> - <name><ret>ErlNifResourceType *</ret> + <name since="OTP R13B04"><ret>ErlNifResourceType *</ret> <nametext>enif_open_resource_type(ErlNifEnv* env, const char* module_str, const char* name, ErlNifResourceDtor* dtor, ErlNifResourceFlags flags, ErlNifResourceFlags* tried)</nametext> @@ -2249,15 +2743,35 @@ enif_map_iterator_destroy(env, &iter);</code> returns <c>NULL</c> and sets <c>*tried</c> to <c>flags</c>. It is allowed to set <c>tried</c> to <c>NULL</c>.</p> <p>Notice that <c>enif_open_resource_type</c> is only allowed to be - called in the three callbacks - <seealso marker="#load"><c>load</c></seealso>, - <seealso marker="#reload"><c>reload</c></seealso>, and + called in the two callbacks + <seealso marker="#load"><c>load</c></seealso> and <seealso marker="#upgrade"><c>upgrade</c></seealso>.</p> + <p>See also <seealso marker="#enif_open_resource_type_x"> + <c>enif_open_resource_type_x</c></seealso>.</p> + </desc> + </func> + + <func> + <name since="OTP 20.0"><ret>ErlNifResourceType *</ret> + <nametext>enif_open_resource_type_x(ErlNifEnv* env, const char* name, + const ErlNifResourceTypeInit* init, + ErlNifResourceFlags flags, ErlNifResourceFlags* tried)</nametext> + </name> + <fsummary>Create or takeover a resource type.</fsummary> + <desc> + <p>Same as <seealso marker="#enif_open_resource_type"><c>enif_open_resource_type</c></seealso> + except it accepts additional callback functions for resource types that are + used together with <seealso marker="#enif_select"><c>enif_select</c></seealso> + and <seealso marker="#enif_monitor_process"><c>enif_monitor_process</c></seealso>.</p> + <p>Argument <c>init</c> is a pointer to an + <seealso marker="#ErlNifResourceTypeInit"><c>ErlNifResourceTypeInit</c></seealso> + structure that contains the function pointers for destructor, down and stop callbacks + for the resource type.</p> </desc> </func> <func> - <name><ret>int</ret><nametext>enif_port_command(ErlNifEnv* env, const + <name since="OTP 19.0"><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> @@ -2273,7 +2787,7 @@ enif_map_iterator_destroy(env, &iter);</code> <item>The port ID of the receiving port. The port ID is to 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 + <item>The environment of the message term. Can be a process independent environment allocated with <seealso marker="#enif_alloc_env"> <c>enif_alloc_env</c></seealso> or <c>NULL</c>.</item> <tag><c>msg</c></tag> @@ -2300,20 +2814,18 @@ enif_map_iterator_destroy(env, &iter);</code> </func> <func> - <name><ret>void *</ret> + <name since="OTP R13B04"><ret>void *</ret> <nametext>enif_priv_data(ErlNifEnv* env)</nametext></name> <fsummary>Get the private data of a NIF library.</fsummary> <desc> <p>Returns the pointer to the private data that was set by - <seealso marker="#load"><c>load</c></seealso>, - <seealso marker="#reload"><c>reload</c></seealso>, or + <seealso marker="#load"><c>load</c></seealso> or <seealso marker="#upgrade"><c>upgrade</c></seealso>.</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* + <name since="OTP 18.0"><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> @@ -2336,7 +2848,21 @@ enif_map_iterator_destroy(env, &iter);</code> </func> <func> - <name><ret>int</ret> + <name since="OTP 20.2"><ret>void *</ret> + <nametext>enif_realloc(void* ptr, size_t size)</nametext></name> + <fsummary>Reallocate dynamic memory.</fsummary> + <desc> + <p>Reallocates memory allocated by + <seealso marker="#enif_alloc"><c>enif_alloc</c></seealso> to + <c>size</c> bytes.</p> + <p>Returns <c>NULL</c> if the reallocation fails.</p> + <p>The returned pointer is suitably aligned for any built-in type that + fit in the allocated memory.</p> + </desc> + </func> + + <func> + <name since="OTP R13B04"><ret>int</ret> <nametext>enif_realloc_binary(ErlNifBinary* bin, size_t size)</nametext> </name> <fsummary>Change the size of a binary.</fsummary> @@ -2350,7 +2876,7 @@ enif_map_iterator_destroy(env, &iter);</code> </func> <func> - <name><ret>void</ret> + <name since=""><ret>void</ret> <nametext>enif_release_binary(ErlNifBinary* bin)</nametext></name> <fsummary>Release a binary.</fsummary> <desc> @@ -2361,11 +2887,11 @@ enif_map_iterator_destroy(env, &iter);</code> </func> <func> - <name><ret>void</ret> + <name since="OTP R13B04"><ret>void</ret> <nametext>enif_release_resource(void* obj)</nametext></name> <fsummary>Release a resource object.</fsummary> <desc> - <p>Removes a reference to resource object <c>obj</c>obtained from + <p>Removes a reference to resource object <c>obj</c> obtained from <seealso marker="#enif_alloc_resource"> <c>enif_alloc_resource</c></seealso>. The resource object is destructed when the last reference is removed. @@ -2380,7 +2906,7 @@ enif_map_iterator_destroy(env, &iter);</code> </func> <func> - <name><ret>ErlNifRWLock *</ret> + <name since="OTP R13B04"><ret>ErlNifRWLock *</ret> <nametext>enif_rwlock_create(char *name)</nametext></name> <fsummary></fsummary> <desc> @@ -2390,7 +2916,7 @@ enif_map_iterator_destroy(env, &iter);</code> </func> <func> - <name><ret>void</ret> + <name since="OTP R13B04"><ret>void</ret> <nametext>enif_rwlock_destroy(ErlNifRWLock *rwlck)</nametext></name> <fsummary></fsummary> <desc> @@ -2400,7 +2926,17 @@ enif_map_iterator_destroy(env, &iter);</code> </func> <func> - <name><ret>void</ret> + <name since="OTP 21.0"><ret>char*</ret> + <nametext>enif_rwlock_name(ErlNifRWLock* rwlck)</nametext></name> + <fsummary></fsummary> + <desc> + <p>Same as <seealso marker="erl_driver#erl_drv_rwlock_name"> + <c>erl_drv_rwlock_name</c></seealso>.</p> + </desc> + </func> + + <func> + <name since="OTP R13B04"><ret>void</ret> <nametext>enif_rwlock_rlock(ErlNifRWLock *rwlck)</nametext></name> <fsummary></fsummary> <desc> @@ -2410,7 +2946,7 @@ enif_map_iterator_destroy(env, &iter);</code> </func> <func> - <name><ret>void</ret> + <name since="OTP R13B04"><ret>void</ret> <nametext>enif_rwlock_runlock(ErlNifRWLock *rwlck)</nametext></name> <fsummary></fsummary> <desc> @@ -2420,7 +2956,7 @@ enif_map_iterator_destroy(env, &iter);</code> </func> <func> - <name><ret>void</ret> + <name since="OTP R13B04"><ret>void</ret> <nametext>enif_rwlock_rwlock(ErlNifRWLock *rwlck)</nametext></name> <fsummary></fsummary> <desc> @@ -2430,7 +2966,7 @@ enif_map_iterator_destroy(env, &iter);</code> </func> <func> - <name><ret>void</ret> + <name since="OTP R13B04"><ret>void</ret> <nametext>enif_rwlock_rwunlock(ErlNifRWLock *rwlck)</nametext></name> <fsummary></fsummary> <desc> @@ -2440,7 +2976,7 @@ enif_map_iterator_destroy(env, &iter);</code> </func> <func> - <name><ret>int</ret> + <name since="OTP R13B04"><ret>int</ret> <nametext>enif_rwlock_tryrlock(ErlNifRWLock *rwlck)</nametext></name> <fsummary></fsummary> <desc> @@ -2450,7 +2986,7 @@ enif_map_iterator_destroy(env, &iter);</code> </func> <func> - <name><ret>int</ret> + <name since="OTP R13B04"><ret>int</ret> <nametext>enif_rwlock_tryrwlock(ErlNifRWLock *rwlck)</nametext></name> <fsummary></fsummary> <desc> @@ -2460,7 +2996,7 @@ enif_map_iterator_destroy(env, &iter);</code> </func> <func> - <name><ret>ERL_NIF_TERM</ret><nametext>enif_schedule_nif(ErlNifEnv* env, + <name since="OTP 17.3"><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> @@ -2470,9 +3006,6 @@ enif_map_iterator_destroy(env, &iter);</code> 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.</p> - <p><em>The dirty NIF functionality described here is - experimental.</em> You have to enable support for dirty - schedulers when building OTP to try out the functionality.</p> <taglist> <tag><c>fun_name</c></tag> <item> @@ -2483,13 +3016,13 @@ enif_map_iterator_destroy(env, &iter);</code> <tag><c>flags</c></tag> <item> <p>Must be set to <c>0</c> for a regular NIF. If the emulator was - built with the experimental dirty scheduler support enabled, + built with 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, an attempt to schedule such a job - results in a <c>badarg</c> exception.</p> + results in a <c>notsup</c> exception.</p> </item> <tag><c>argc</c> and <c>argv</c></tag> <item> @@ -2508,33 +3041,128 @@ enif_map_iterator_destroy(env, &iter);</code> </func> <func> - <name><ret>ErlNifPid *</ret> + <name since="OTP 20.0"><ret>int</ret> + <nametext>enif_select(ErlNifEnv* env, ErlNifEvent event, enum ErlNifSelectFlags mode, + void* obj, const ErlNifPid* pid, ERL_NIF_TERM ref)</nametext> + </name> + <fsummary>Manage subscription on IO event.</fsummary> + <desc> + <p>This function can be used to receive asynchronous notifications + when OS-specific event objects become ready for either read or write operations.</p> + <p>Argument <c>event</c> identifies the event object. On Unix + systems, the functions <c>select</c>/<c>poll</c> are used. The event + object must be a socket, pipe or other file descriptor object that + <c>select</c>/<c>poll</c> can use.</p> + <p>Argument <c>mode</c> describes the type of events to wait for. It can be + <c>ERL_NIF_SELECT_READ</c>, <c>ERL_NIF_SELECT_WRITE</c> or a bitwise + OR combination to wait for both. It can also be <c>ERL_NIF_SELECT_STOP</c> + which is described further below. When a read or write event is triggered, + a notification message like this is sent to the process identified by + <c>pid</c>:</p> + <code type="none">{select, Obj, Ref, ready_input | ready_output}</code> + <p><c>ready_input</c> or <c>ready_output</c> indicates if the event object + is ready for reading or writing.</p> + <p>Argument <c>pid</c> may be <c>NULL</c> to indicate the calling process.</p> + <p>Argument <c>obj</c> is a resource object obtained from + <seealso marker="#enif_alloc_resource"><c>enif_alloc_resource</c></seealso>. + The purpose of the resource objects is as a container of the event object + to manage its state and lifetime. A handle to the resource is received + in the notification message as <c>Obj</c>.</p> + <p>Argument <c>ref</c> must be either a reference obtained from + <seealso marker="erlang#make_ref-0"><c>erlang:make_ref/0</c></seealso> + or the atom <c>undefined</c>. It will be passed as <c>Ref</c> in the notifications. + If a selective <c>receive</c> statement is used to wait for the notification + then a reference created just before the <c>receive</c> will exploit a runtime + optimization that bypasses all earlier received messages in the queue.</p> + <p>The notifications are one-shot only. To receive further notifications of the same + type (read or write), repeated calls to <c>enif_select</c> must be made + after receiving each notification.</p> + <p>Use <c>ERL_NIF_SELECT_STOP</c> as <c>mode</c> in order to safely + close an event object that has been passed to <c>enif_select</c>. The + <seealso marker="#ErlNifResourceStop"><c>stop</c></seealso> callback + of the resource <c>obj</c> will be called when it is safe to close + the event object. This safe way of closing event objects must be used + even if all notifications have been received and no further calls to + <c>enif_select</c> have been made.</p> + <p>The first call to <c>enif_select</c> for a specific OS <c>event</c> will establish + a relation between the event object and the containing resource. All subsequent calls + for an <c>event</c> must pass its containing resource as argument + <c>obj</c>. The relation is dissolved when <c>enif_select</c> has + been called with <c>mode</c> as <c>ERL_NIF_SELECT_STOP</c> and the + corresponding <c>stop</c> callback has returned. A resource can contain + several event objects but one event object can only be contained within + one resource. A resource will not be destructed until all its contained relations + have been dissolved.</p> + <note> + <p>Use <seealso marker="#enif_monitor_process"><c>enif_monitor_process</c></seealso> + together with <c>enif_select</c> to detect failing Erlang + processes and prevent them from causing permanent leakage of resources + and their contained OS event objects.</p> + </note> + <p>Returns a non-negative value on success where the following bits can be set:</p> + <taglist> + <tag><c>ERL_NIF_SELECT_STOP_CALLED</c></tag> + <item>The stop callback was called directly by <c>enif_select</c>.</item> + <tag><c>ERL_NIF_SELECT_STOP_SCHEDULED</c></tag> + <item>The stop callback was scheduled to run on some other thread + or later by this thread.</item> + </taglist> + <p>Returns a negative value if the call failed where the following bits can be set:</p> + <taglist> + <tag><c>ERL_NIF_SELECT_INVALID_EVENT</c></tag> + <item>Argument <c>event</c> is not a valid OS event object.</item> + <tag><c>ERL_NIF_SELECT_FAILED</c></tag> + <item>The system call failed to add the event object to the poll set.</item> + </taglist> + <note> + <p>Use bitwise AND to test for specific bits in the return value. + New significant bits may be added in future releases to give more detailed + information for both failed and successful calls. Do NOT use equality tests + like <c>==</c>, as that may cause your application to stop working.</p> + <p>Example:</p> + <code type="none"> +retval = enif_select(env, fd, ERL_NIF_SELECT_STOP, resource, ref); +if (retval < 0) { + /* handle error */ +} +/* Success! */ +if (retval & ERL_NIF_SELECT_STOP_CALLED) { + /* ... */ +} +</code> + </note> + </desc> + </func> + + <func> + <name since="OTP R14B"><ret>ErlNifPid *</ret> <nametext>enif_self(ErlNifEnv* caller_env, ErlNifPid* pid)</nametext> </name> <fsummary>Get the pid of the calling process.</fsummary> <desc> - <p>Initializes the pid variable <c>*pid</c> to represent the - calling process.</p> - <p>Returns <c>pid</c>.</p> + <p>Initializes the <seealso marker="#ErlNifPid"><c>ErlNifPid</c></seealso> + variable at <c>*pid</c> to represent the calling process.</p> + <p>Returns <c>pid</c> if successful, or NULL if <c>caller_env</c> is not + a <seealso marker="#ErlNifEnv">process bound environment</seealso>.</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> + <name since="OTP R14B"><ret>int</ret><nametext>enif_send(ErlNifEnv* caller_env, + ErlNifPid* to_pid, ErlNifEnv* msg_env, ERL_NIF_TERM msg)</nametext></name> <fsummary>Send a message to a process.</fsummary> <desc> <p>Sends a message to a process.</p> <taglist> - <tag><c>env</c></tag> - <item>The environment of the calling process. Must be <c>NULL</c> - only if calling from a created thread.</item> + <tag><c>caller_env</c></tag> + <item>The environment of the calling process or callback. Must be <c>NULL</c> + only if calling from a custom thread not spawned by ERTS.</item> <tag><c>*to_pid</c></tag> <item>The pid of the receiving process. The pid is to refer to a process on the local node.</item> <tag><c>msg_env</c></tag> <item>The environment of the message term. Must be a - process-independent environment allocated with + process independent environment allocated with <seealso marker="#enif_alloc_env"><c>enif_alloc_env</c></seealso> or NULL.</item> <tag><c>msg</c></tag> @@ -2554,7 +3182,7 @@ enif_map_iterator_destroy(env, &iter);</code> <c>enif_free_env</c></seealso> of cleared for reuse with <seealso marker="#enif_clear_env"><c>enif_clear_env</c></seealso>.</p> <p>If <c>msg_env</c> is set to <c>NULL</c>, the <c>msg</c> term is - copied and the original term and its environemt is still valid after + copied and the original term and its environment 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 @@ -2567,7 +3195,7 @@ enif_map_iterator_destroy(env, &iter);</code> </func> <func> - <name><ret>unsigned</ret> + <name since="OTP R13B04"><ret>unsigned</ret> <nametext>enif_sizeof_resource(void* obj)</nametext></name> <fsummary>Get the byte size of a resource object.</fsummary> <desc> @@ -2578,17 +3206,21 @@ enif_map_iterator_destroy(env, &iter);</code> </func> <func> - <name><ret>int</ret><nametext>enif_snprintf(char *str, size_t size, const + <name since="OTP 19.0"><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> + <c>"%T"</c>, which formats Erlang terms of type + <seealso marker="#ERL_NIF_TERM"><c>ERL_NIF_TERM</c></seealso>.</p> + <p>This function is primarily intended for debugging purpose. It is not + recommended to print very large terms with <c>%T</c>. The function may + change <c>errno</c>, even if successful.</p> </desc> </func> <func> - <name><ret>void</ret><nametext>enif_system_info(ErlNifSysInfo + <name since="OTP R13B04"><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> @@ -2598,7 +3230,7 @@ enif_map_iterator_destroy(env, &iter);</code> </func> <func> - <name><ret>int</ret><nametext>enif_term_to_binary(ErlNifEnv *env, + <name since="OTP 19.0"><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> @@ -2615,7 +3247,7 @@ enif_map_iterator_destroy(env, &iter);</code> </func> <func> - <name><ret>int</ret> + <name since="OTP R13B04"><ret>int</ret> <nametext>enif_thread_create(char *name,ErlNifTid *tid,void * (*func)(void *),void *args,ErlNifThreadOpts *opts)</nametext></name> @@ -2627,7 +3259,7 @@ enif_map_iterator_destroy(env, &iter);</code> </func> <func> - <name><ret>void</ret> + <name since="OTP R13B04"><ret>void</ret> <nametext>enif_thread_exit(void *resp)</nametext></name> <fsummary></fsummary> <desc> @@ -2637,7 +3269,7 @@ enif_map_iterator_destroy(env, &iter);</code> </func> <func> - <name><ret>int</ret> + <name since="OTP R13B04"><ret>int</ret> <nametext>enif_thread_join(ErlNifTid, void **respp)</nametext></name> <fsummary></fsummary> <desc> @@ -2647,7 +3279,17 @@ enif_map_iterator_destroy(env, &iter);</code> </func> <func> - <name><ret>ErlNifThreadOpts *</ret> + <name since="OTP 21.0"><ret>char*</ret> + <nametext>enif_thread_name(ErlNifTid tid)</nametext></name> + <fsummary>Thread name</fsummary> + <desc> + <p>Same as <seealso marker="erl_driver#erl_drv_thread_name"> + <c>erl_drv_thread_name</c></seealso>.</p> + </desc> + </func> + + <func> + <name since="OTP R13B04"><ret>ErlNifThreadOpts *</ret> <nametext>enif_thread_opts_create(char *name)</nametext></name> <fsummary></fsummary> <desc> @@ -2657,7 +3299,7 @@ enif_map_iterator_destroy(env, &iter);</code> </func> <func> - <name><ret>void</ret> + <name since="OTP R13B04"><ret>void</ret> <nametext>enif_thread_opts_destroy(ErlNifThreadOpts *opts)</nametext> </name> <fsummary></fsummary> @@ -2668,7 +3310,7 @@ enif_map_iterator_destroy(env, &iter);</code> </func> <func> - <name><ret>ErlNifTid</ret> + <name since="OTP R13B04"><ret>ErlNifTid</ret> <nametext>enif_thread_self(void)</nametext></name> <fsummary></fsummary> <desc> @@ -2678,7 +3320,7 @@ enif_map_iterator_destroy(env, &iter);</code> </func> <func> - <name><ret>int</ret> + <name since="OTP 19.0"><ret>int</ret> <nametext>enif_thread_type(void)</nametext></name> <fsummary>Determine type of current thread</fsummary> <desc> @@ -2700,7 +3342,7 @@ enif_map_iterator_destroy(env, &iter);</code> </func> <func> - <name><ret>ErlNifTime</ret> + <name since="OTP 18.3"><ret>ErlNifTime</ret> <nametext>enif_time_offset(ErlNifTimeUnit time_unit)</nametext></name> <fsummary>Get current time offset.</fsummary> <desc> @@ -2722,7 +3364,7 @@ enif_map_iterator_destroy(env, &iter);</code> </func> <func> - <name><ret>void *</ret> + <name since="OTP R13B04"><ret>void *</ret> <nametext>enif_tsd_get(ErlNifTSDKey key)</nametext></name> <fsummary></fsummary> <desc> @@ -2732,7 +3374,7 @@ enif_map_iterator_destroy(env, &iter);</code> </func> <func> - <name><ret>int</ret> + <name since="OTP R13B04"><ret>int</ret> <nametext>enif_tsd_key_create(char *name, ErlNifTSDKey *key)</nametext> </name> <fsummary></fsummary> @@ -2743,7 +3385,7 @@ enif_map_iterator_destroy(env, &iter);</code> </func> <func> - <name><ret>void</ret> + <name since="OTP R13B04"><ret>void</ret> <nametext>enif_tsd_key_destroy(ErlNifTSDKey key)</nametext></name> <fsummary></fsummary> <desc> @@ -2753,7 +3395,7 @@ enif_map_iterator_destroy(env, &iter);</code> </func> <func> - <name><ret>void</ret> + <name since="OTP R13B04"><ret>void</ret> <nametext>enif_tsd_set(ErlNifTSDKey key, void *data)</nametext></name> <fsummary></fsummary> <desc> @@ -2761,6 +3403,87 @@ enif_map_iterator_destroy(env, &iter);</code> <c>erl_drv_tsd_set</c></seealso>.</p> </desc> </func> + + <func> + <name since="OTP 21.0"><ret>int</ret> + <nametext>enif_vfprintf(FILE *stream, const char *format, va_list ap) + </nametext></name> + <fsummary>Format strings and Erlang terms.</fsummary> + <desc> + <p>Equivalent to <seealso marker="#enif_fprintf"><c>enif_fprintf</c></seealso> + except that its called with a <c>va_list</c> instead of a variable number of + arguments.</p> + </desc> + </func> + + <func> + <name since="OTP 21.0"><ret>int</ret> + <nametext>enif_vsnprintf(char *str, size_t size, const char *format, va_list ap) + </nametext></name> + <fsummary>Format strings and Erlang terms.</fsummary> + <desc> + <p>Equivalent to <seealso marker="#enif_snprintf"><c>enif_snprintf</c></seealso> + except that its called with a <c>va_list</c> instead of a variable number of + arguments.</p> + </desc> + </func> + + <func> + <name since="OTP 20.0"><ret>int</ret> + <nametext>enif_whereis_pid(ErlNifEnv *env, + ERL_NIF_TERM name, ErlNifPid *pid)</nametext></name> + <fsummary>Looks up a process by its registered name.</fsummary> + <desc> + <p>Looks up a process by its registered name.</p> + <taglist> + <tag><c>env</c></tag> + <item>The environment of the calling process. Must be <c>NULL</c> + only if calling from a created thread.</item> + <tag><c>name</c></tag> + <item>The name of a registered process, as an atom.</item> + <tag><c>*pid</c></tag> + <item>The <seealso marker="#ErlNifPid"><c>ErlNifPid</c></seealso> + in which the resolved process id is stored.</item> + </taglist> + <p>On success, sets <c>*pid</c> to the local process registered with + <c>name</c> and returns <c>true</c>. If <c>name</c> is not a + registered process, or is not an atom, <c>false</c> is returned and + <c>*pid</c> is unchanged.</p> + <p>Works as <seealso marker="erlang#whereis-1"> + <c>erlang:whereis/1</c></seealso>, but restricted to processes. See + <seealso marker="#enif_whereis_port"><c>enif_whereis_port</c></seealso> + to resolve registered ports.</p> + </desc> + </func> + + <func> + <name since="OTP 20.0"><ret>int</ret> + <nametext>enif_whereis_port(ErlNifEnv *env, + ERL_NIF_TERM name, ErlNifPort *port)</nametext></name> + <fsummary>Looks up a port by its registered name.</fsummary> + <desc> + <p>Looks up a port by its registered name.</p> + <taglist> + <tag><c>env</c></tag> + <item>The environment of the calling process. Must be <c>NULL</c> + only if calling from a created thread.</item> + <tag><c>name</c></tag> + <item>The name of a registered port, as an atom.</item> + <tag><c>*port</c></tag> + <item>The <seealso marker="#ErlNifPort"><c>ErlNifPort</c></seealso> + in which the resolved port id is stored.</item> + </taglist> + <p>On success, sets <c>*port</c> to the port registered with + <c>name</c> and returns <c>true</c>. If <c>name</c> is not a + registered port, or is not an atom, <c>false</c> is returned and + <c>*port</c> is unchanged.</p> + <p>Works as <seealso marker="erlang#whereis-1"> + <c>erlang:whereis/1</c></seealso>, but restricted to ports. See + <seealso marker="#enif_whereis_pid"><c>enif_whereis_pid</c></seealso> + to resolve registered processes.</p> + </desc> + </func> + </funcs> <section> diff --git a/erts/doc/src/erl_prim_loader.xml b/erts/doc/src/erl_prim_loader.xml index 286bac6c93..043d11b7b4 100644 --- a/erts/doc/src/erl_prim_loader.xml +++ b/erts/doc/src/erl_prim_loader.xml @@ -29,7 +29,7 @@ <rev></rev> <file>erl_prim_loader.xml</file> </header> - <module>erl_prim_loader</module> + <module since="">erl_prim_loader</module> <modulesummary>Low-level Erlang loader.</modulesummary> <description> <p>This module is used to load all Erlang modules into @@ -47,7 +47,7 @@ <funcs> <func> - <name name="get_file" arity="1"/> + <name name="get_file" arity="1" since=""/> <fsummary>Get a file.</fsummary> <desc> <p>Fetches a file using the low-level loader. @@ -65,7 +65,7 @@ </func> <func> - <name name="get_path" arity="0"/> + <name name="get_path" arity="0" since=""/> <fsummary>Get the path set in the loader.</fsummary> <desc> <p>Gets the path set in the loader. The path is @@ -75,7 +75,7 @@ </func> <func> - <name name="list_dir" arity="1"/> + <name name="list_dir" arity="1" since=""/> <fsummary>List files in a directory.</fsummary> <desc> <p>Lists all the files in a directory. Returns @@ -92,7 +92,7 @@ </func> <func> - <name name="read_file_info" arity="1"/> + <name name="read_file_info" arity="1" since=""/> <fsummary>Get information about a file.</fsummary> <desc> <p>Retrieves information about a file. Returns @@ -114,7 +114,7 @@ </func> <func> - <name name="read_link_info" arity="1"/> + <name name="read_link_info" arity="1" since="OTP 17.1.2"/> <fsummary>Get information about a link or file.</fsummary> <desc> <p>Works like @@ -131,7 +131,7 @@ </func> <func> - <name name="set_path" arity="1"/> + <name name="set_path" arity="1" since=""/> <fsummary>Set the path of the loader.</fsummary> <desc> <p>Sets the path of the loader if diff --git a/erts/doc/src/erl_tracer.xml b/erts/doc/src/erl_tracer.xml index 83eef374ca..fa4717bc2f 100644 --- a/erts/doc/src/erl_tracer.xml +++ b/erts/doc/src/erl_tracer.xml @@ -4,7 +4,7 @@ <erlref> <header> <copyright> - <year>2016</year><year>2016</year> + <year>2016</year><year>2017</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -28,7 +28,7 @@ <date></date> <rev></rev> </header> - <module>erl_tracer</module> + <module since="OTP 19.0">erl_tracer</module> <modulesummary>Erlang tracer behavior.</modulesummary> <description> <p>This behavior module implements the back end of the Erlang @@ -103,7 +103,7 @@ <item>If set the tracer has been requested to include a time stamp.</item> <tag><c>extra</c></tag> - <item>If set the tracepoint has included additonal data about + <item>If set the tracepoint has included additional 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 element in the trace tuples described in @@ -195,7 +195,7 @@ <funcs> <func> - <name>Module:enabled(TraceTag, TracerState, Tracee) -> Result</name> + <name since="OTP 19.0">Module:enabled(TraceTag, TracerState, Tracee) -> Result</name> <fsummary>Check if a trace event is to be generated.</fsummary> <type> <v>TraceTag = <seealso marker="#type-trace_tag"> @@ -224,7 +224,7 @@ </func> <func> - <name>Module:enabled_call(TraceTag, TracerState, Tracee) -> Result</name> + <name since="OTP 19.0">Module:enabled_call(TraceTag, TracerState, Tracee) -> Result</name> <fsummary>Check if a trace event is to be generated.</fsummary> <type> <v>TraceTag = <seealso marker="#type-trace_tag_call"> @@ -244,7 +244,7 @@ </func> <func> - <name>Module:enabled_garbage_collection(TraceTag, TracerState, Tracee) -> Result</name> + <name since="OTP 19.0">Module:enabled_garbage_collection(TraceTag, TracerState, Tracee) -> Result</name> <fsummary>Check if a trace event is to be generated.</fsummary> <type> <v>TraceTag = <seealso marker="#type-trace_tag_gc"> @@ -264,7 +264,7 @@ </func> <func> - <name>Module:enabled_ports(TraceTag, TracerState, Tracee) -> Result</name> + <name since="OTP 19.0">Module:enabled_ports(TraceTag, TracerState, Tracee) -> Result</name> <fsummary>Check if a trace event is to be generated.</fsummary> <type> <v>TraceTag = <seealso marker="#type-trace_tag_ports"> @@ -284,7 +284,7 @@ </func> <func> - <name>Module:enabled_procs(TraceTag, TracerState, Tracee) -> Result</name> + <name since="OTP 19.0">Module:enabled_procs(TraceTag, TracerState, Tracee) -> Result</name> <fsummary>Check if a trace event is to be generated.</fsummary> <type> <v>TraceTag = <seealso marker="#type-trace_tag_procs"> @@ -304,7 +304,7 @@ </func> <func> - <name>Module:enabled_receive(TraceTag, TracerState, Tracee) -> Result + <name since="OTP 19.0">Module:enabled_receive(TraceTag, TracerState, Tracee) -> Result </name> <fsummary>Check if a trace event is to be generated.</fsummary> <type> @@ -325,7 +325,7 @@ </func> <func> - <name>Module:enabled_running_ports(TraceTag, TracerState, Tracee) -> + <name since="OTP 19.0">Module:enabled_running_ports(TraceTag, TracerState, Tracee) -> Result</name> <fsummary>Check if a trace event is to be generated.</fsummary> <type> @@ -346,7 +346,7 @@ </func> <func> - <name>Module:enabled_running_procs(TraceTag, TracerState, Tracee) -> + <name since="OTP 19.0">Module:enabled_running_procs(TraceTag, TracerState, Tracee) -> Result</name> <fsummary>Check if a trace event is to be generated.</fsummary> <type> @@ -368,7 +368,7 @@ </func> <func> - <name>Module:enabled_send(TraceTag, TracerState, Tracee) -> Result</name> + <name since="OTP 19.0">Module:enabled_send(TraceTag, TracerState, Tracee) -> Result</name> <fsummary>Check if a trace event is to be generated.</fsummary> <type> <v>TraceTag = <seealso marker="#type-trace_tag_send"> @@ -388,7 +388,7 @@ </func> <func> - <name>Module:trace(TraceTag, TracerState, Tracee, TraceTerm, + <name since="OTP 19.0">Module:trace(TraceTag, TracerState, Tracee, TraceTerm, Opts) -> Result</name> <fsummary>Check if a trace event is to be generated.</fsummary> <type> @@ -417,7 +417,7 @@ </func> <func> - <name name="trace">Module:trace(seq_trace, TracerState, Label, + <name name="trace" since="OTP 19.0">Module:trace(seq_trace, TracerState, Label, SeqTraceInfo, Opts) -> Result</name> <fsummary>Check if a sequence trace event is to be generated.</fsummary> <type> @@ -439,7 +439,7 @@ </func> <func> - <name>Module:trace_call(TraceTag, TracerState, Tracee, TraceTerm, + <name since="OTP 19.0">Module:trace_call(TraceTag, TracerState, Tracee, TraceTerm, Opts) -> Result</name> <fsummary>Check if a trace event is to be generated.</fsummary> <type> @@ -463,7 +463,7 @@ </func> <func> - <name>Module:trace_garbage_collection(TraceTag, TracerState, Tracee, + <name since="OTP 19.0">Module:trace_garbage_collection(TraceTag, TracerState, Tracee, TraceTerm, Opts) -> Result</name> <fsummary>Check if a trace event is to be generated.</fsummary> <type> @@ -487,7 +487,7 @@ </func> <func> - <name>Module:trace_ports(TraceTag, TracerState, Tracee, TraceTerm, + <name since="OTP 19.0">Module:trace_ports(TraceTag, TracerState, Tracee, TraceTerm, Opts) -> Result</name> <fsummary>Check if a trace event is to be generated.</fsummary> <type> @@ -511,7 +511,7 @@ </func> <func> - <name>Module:trace_procs(TraceTag, TracerState, Tracee, TraceTerm, + <name since="OTP 19.0">Module:trace_procs(TraceTag, TracerState, Tracee, TraceTerm, Opts) -> Result</name> <fsummary>Check if a trace event is to be generated.</fsummary> <type> @@ -535,7 +535,7 @@ </func> <func> - <name>Module:trace_receive(TraceTag, TracerState, Tracee, TraceTerm, + <name since="OTP 19.0">Module:trace_receive(TraceTag, TracerState, Tracee, TraceTerm, Opts) -> Result</name> <fsummary>Check if a trace event is to be generated.</fsummary> <type> @@ -559,7 +559,7 @@ </func> <func> - <name>Module:trace_running_ports(TraceTag, TracerState, Tracee, + <name since="OTP 19.0">Module:trace_running_ports(TraceTag, TracerState, Tracee, TraceTerm, Opts) -> Result</name> <fsummary>Check if a trace event is to be generated.</fsummary> <type> @@ -583,7 +583,7 @@ </func> <func> - <name>Module:trace_running_procs(TraceTag, TracerState, Tracee, + <name since="OTP 19.0">Module:trace_running_procs(TraceTag, TracerState, Tracee, TraceTerm, Opts) -> Result</name> <fsummary>Check if a trace event is to be generated.</fsummary> <type> @@ -607,7 +607,7 @@ </func> <func> - <name>Module:trace_send(TraceTag, TracerState, Tracee, TraceTerm, + <name since="OTP 19.0">Module:trace_send(TraceTag, TracerState, Tracee, TraceTerm, Opts) -> Result</name> <fsummary>Check if a trace event is to be generated.</fsummary> <type> @@ -653,7 +653,7 @@ ok <0.37.0> 3> erlang:trace(new, true, [send,{tracer, erl_msg_tracer, Tracer}]). 0 -{<0.39.0>,<0.27.0>} +{trace,<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>} @@ -684,7 +684,7 @@ trace(_, _, _, _, _) -> <p><c>erl_msg_tracer.c</c>:</p> <pre> -#include "erl_nif.h" +#include <erl_nif.h> /* NIF interface declarations */ static int load(ErlNifEnv* env, void** priv_data, ERL_NIF_TERM load_info); @@ -758,18 +758,21 @@ static ERL_NIF_TERM enabled(ErlNifEnv* env, int argc, const ERL_NIF_TERM argv[]) /* * argv[0]: TraceTag, should only be 'send' - * argv[1]: TracerState, process to send {argv[2], argv[4]} to + * argv[1]: TracerState, process to send {Tracee, Recipient} to * argv[2]: Tracee - * argv[3]: Recipient - * argv[4]: Options, ignored + * argv[3]: Message + * argv[4]: Options, map containing Recipient */ static ERL_NIF_TERM trace(ErlNifEnv* env, int argc, const ERL_NIF_TERM argv[]) { ErlNifPid to_pid; + ERL_NIF_TERM recipient, msg; 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]); + if (enif_get_map_value(env, argv[4], enif_make_atom(env, "extra"), &recipient)) { + msg = enif_make_tuple3(env, enif_make_atom(env, "trace"), argv[2], recipient); enif_send(env, &to_pid, NULL, msg); + } } return enif_make_atom(env, "ok"); diff --git a/erts/doc/src/erlang.xml b/erts/doc/src/erlang.xml index 24a091073d..a42323b13d 100644 --- a/erts/doc/src/erlang.xml +++ b/erts/doc/src/erlang.xml @@ -4,7 +4,7 @@ <erlref> <header> <copyright> - <year>1996</year><year>2017</year> + <year>1996</year><year>2018</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -29,15 +29,15 @@ <rev></rev> <file>erlang.xml</file> </header> - <module>erlang</module> + <module since="">erlang</module> <modulesummary>The Erlang BIFs.</modulesummary> <description> <p>By convention, most Built-In Functions (BIFs) are included 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. For example, the calls <c>atom_to_list(Erlang)</c> - and <c>erlang:atom_to_list(Erlang)</c> are identical.</p> + 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> @@ -53,13 +53,21 @@ <datatypes> <datatype> - <name>ext_binary()</name> + <name name="ext_binary"/> <desc> <p>A binary data object, structured according to the Erlang external term format.</p> </desc> </datatype> <datatype> + <name name="iovec"/> + <desc> + <p>A list of binaries. This datatype is useful to use + together with <seealso marker="erl_nif#enif_inspect_iovec"> + <c>enif_inspect_iovec</c></seealso>.</p> + </desc> + </datatype> + <datatype> <name name="message_queue_data"></name> <desc> <p>See <seealso marker="#process_flag_message_queue_data"> @@ -181,17 +189,30 @@ </taglist> </desc> </datatype> + + <datatype> + <name name="dist_handle"></name> + <desc> + <p>An opaque handle identifing a distribution channel.</p> + </desc> + </datatype> + + <datatype> + <name name="nif_resource"></name> + <desc> + <p>An opaque handle identifing a + <seealso marker="erl_nif#resource_objects">NIF resource object + </seealso>.</p> + </desc> + </datatype> + </datatypes> <funcs> <func> - <name name="abs" arity="1" clause_i="1"/> - <name name="abs" arity="1" clause_i="2"/> + <name name="abs" arity="1" clause_i="1" since=""/> + <name name="abs" arity="1" clause_i="2" since=""/> <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 @@ -206,7 +227,7 @@ </func> <func> - <name name="adler32" arity="1"/> + <name name="adler32" arity="1" since=""/> <fsummary>Compute adler32 checksum.</fsummary> <desc> <p>Computes and returns the adler32 checksum for @@ -215,7 +236,7 @@ </func> <func> - <name name="adler32" arity="2"/> + <name name="adler32" arity="2" since=""/> <fsummary>Compute adler32 checksum.</fsummary> <desc> <p>Continues computing the adler32 checksum by combining @@ -232,7 +253,7 @@ Y = erlang:adler32([Data1,Data2]).</code> </func> <func> - <name name="adler32_combine" arity="3"/> + <name name="adler32_combine" arity="3" since=""/> <fsummary>Combine two adler32 checksums.</fsummary> <desc> <p>Combines two previously computed adler32 checksums. @@ -251,7 +272,7 @@ Z = erlang:adler32_combine(X,Y,iolist_size(Data2)).</code> </func> <func> - <name name="append_element" arity="2"/> + <name name="append_element" arity="2" since=""/> <fsummary>Append an extra element to a tuple.</fsummary> <desc> <p>Returns a new tuple that has one element more than @@ -268,7 +289,7 @@ Z = erlang:adler32_combine(X,Y,iolist_size(Data2)).</code> </func> <func> - <name name="apply" arity="2"/> + <name name="apply" arity="2" since=""/> <fsummary>Apply a function to an argument list.</fsummary> <desc> <p>Calls a fun, passing the elements in <c><anno>Args</anno></c> @@ -286,7 +307,7 @@ Z = erlang:adler32_combine(X,Y,iolist_size(Data2)).</code> </func> <func> - <name name="apply" arity="3"/> + <name name="apply" arity="3" since=""/> <fsummary>Apply a function to an argument list.</fsummary> <desc> <p>Returns the result of applying <c>Function</c> in @@ -316,7 +337,7 @@ Z = erlang:adler32_combine(X,Y,iolist_size(Data2)).</code> </func> <func> - <name name="atom_to_binary" arity="2"/> + <name name="atom_to_binary" arity="2" since=""/> <fsummary>Return the binary representation of an atom.</fsummary> <desc> <p>Returns a binary corresponding to the text @@ -325,16 +346,11 @@ Z = erlang:adler32_combine(X,Y,iolist_size(Data2)).</code> is <c>latin1</c>, one byte exists 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> + <c>unicode</c>, the characters are encoded using UTF-8 where + characters may require multiple bytes.</p> <note> - <p><c>atom_to_binary(<anno>Atom</anno>, latin1)</c> never - fails, as 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> then fails if the + <p>As from Erlang/OTP 20, atoms can contain any Unicode character + and <c>atom_to_binary(<anno>Atom</anno>, latin1)</c> may fail if the text representation for <c><anno>Atom</anno></c> contains a Unicode character > 255.</p> </note> @@ -346,7 +362,7 @@ Z = erlang:adler32_combine(X,Y,iolist_size(Data2)).</code> </func> <func> - <name name="atom_to_list" arity="1"/> + <name name="atom_to_list" arity="1" since=""/> <fsummary>Text representation of an atom.</fsummary> <desc> <p>Returns a string corresponding to the text @@ -358,7 +374,7 @@ Z = erlang:adler32_combine(X,Y,iolist_size(Data2)).</code> </func> <func> - <name name="binary_part" arity="2"/> + <name name="binary_part" arity="2" since="OTP R14B"/> <fsummary>Extract a part of a binary.</fsummary> <desc> <p>Extracts the part of the binary described by @@ -383,7 +399,7 @@ Z = erlang:adler32_combine(X,Y,iolist_size(Data2)).</code> </func> <func> - <name name="binary_part" arity="3"/> + <name name="binary_part" arity="3" since="OTP R14B"/> <fsummary>Extract a part of a binary.</fsummary> <desc> <p>The same as <c>binary_part(<anno>Subject</anno>, @@ -393,7 +409,7 @@ Z = erlang:adler32_combine(X,Y,iolist_size(Data2)).</code> </func> <func> - <name name="binary_to_atom" arity="2"/> + <name name="binary_to_atom" arity="2" since=""/> <fsummary>Convert from text representation to an atom.</fsummary> <desc> <p>Returns the atom whose text representation is @@ -402,13 +418,11 @@ Z = erlang:adler32_combine(X,Y,iolist_size(Data2)).</code> 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> + valid UTF-8 sequences.</p> <note> - <p><c>binary_to_atom(<anno>Binary</anno>, utf8)</c> fails if - the binary contains Unicode characters > 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. + <p>As from Erlang/OTP 20, <c>binary_to_atom(<anno>Binary</anno>, utf8)</c> + is capable of encoding any Unicode character. Earlier versions would + fail if the binary contained Unicode characters > 255. For more information about Unicode support in atoms, see the <seealso marker="erl_ext_dist#utf8_atoms">note on UTF-8 encoded atoms</seealso> @@ -419,25 +433,33 @@ Z = erlang:adler32_combine(X,Y,iolist_size(Data2)).</code> > <input>binary_to_atom(<<"Erlang">>, latin1).</input> 'Erlang' > <input>binary_to_atom(<<1024/utf8>>, utf8).</input> -** exception error: bad argument - in function binary_to_atom/2 - called as binary_to_atom(<<208,128>>,utf8)</pre> +'Ѐ'</pre> </desc> </func> <func> - <name name="binary_to_existing_atom" arity="2"/> + <name name="binary_to_existing_atom" arity="2" since=""/> <fsummary>Convert from text representation to an atom.</fsummary> <desc> <p>As <seealso marker="#binary_to_atom/2"><c>binary_to_atom/2</c></seealso>, but the atom must exist.</p> <p>Failure: <c>badarg</c> if the atom does not exist.</p> + <note> + <p>Note that the compiler may optimize away atoms. For + example, the compiler will rewrite + <c>atom_to_list(some_atom)</c> to <c>"some_atom"</c>. If + that expression is the only mention of the atom + <c>some_atom</c> in the containing module, the atom will not + be created when the module is loaded, and a subsequent call + to <c>binary_to_existing_atom(<<"some_atom">>, utf8)</c> + will fail.</p> + </note> </desc> </func> <func> - <name name="binary_to_float" arity="1"/> + <name name="binary_to_float" arity="1" since="OTP R16B"/> <fsummary>Convert from text representation to a float.</fsummary> <desc> <p>Returns the float whose text representation is @@ -451,7 +473,7 @@ Z = erlang:adler32_combine(X,Y,iolist_size(Data2)).</code> </func> <func> - <name name="binary_to_integer" arity="1"/> + <name name="binary_to_integer" arity="1" since="OTP R16B"/> <fsummary>Convert from text representation to an integer.</fsummary> <desc> <p>Returns an integer whose text representation is @@ -465,7 +487,7 @@ Z = erlang:adler32_combine(X,Y,iolist_size(Data2)).</code> </func> <func> - <name name="binary_to_integer" arity="2"/> + <name name="binary_to_integer" arity="2" since="OTP R16B"/> <fsummary>Convert from text representation to an integer.</fsummary> <desc> <p>Returns an integer whose text representation in base @@ -480,7 +502,7 @@ Z = erlang:adler32_combine(X,Y,iolist_size(Data2)).</code> </func> <func> - <name name="binary_to_list" arity="1"/> + <name name="binary_to_list" arity="1" since=""/> <fsummary>Convert a binary to a list.</fsummary> <desc> <p>Returns a list of integers corresponding to the bytes of @@ -489,7 +511,7 @@ Z = erlang:adler32_combine(X,Y,iolist_size(Data2)).</code> </func> <func> - <name name="binary_to_list" arity="3"/> + <name name="binary_to_list" arity="3" since=""/> <fsummary>Convert part of a binary to a list.</fsummary> <type_desc variable="Start">1..byte_size(<c><anno>Binary</anno></c>) </type_desc> @@ -511,7 +533,7 @@ Z = erlang:adler32_combine(X,Y,iolist_size(Data2)).</code> </func> <func> - <name name="binary_to_term" arity="1"/> + <name name="binary_to_term" arity="1" since=""/> <fsummary>Decode an Erlang external term format binary.</fsummary> <desc> <p>Returns an Erlang term that is the result of decoding @@ -537,12 +559,10 @@ hello </func> <func> - <name name="binary_to_term" arity="2"/> + <name name="binary_to_term" arity="2" since="OTP R13B04"/> <fsummary>Decode 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> - <p>Option:</p> + <p>As <c>binary_to_term/1</c>, but takes these options:</p> <taglist> <tag><c>safe</c></tag> <item> @@ -558,18 +578,31 @@ hello 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> <pre> -> <input>binary_to_term(<<131,100,0,5,104,101,108,108,111>>, [safe]).</input> +> <input>binary_to_term(<<131,100,0,5,"hello">>, [safe]).</input> ** exception error: bad argument > <input>hello.</input> hello -> <input>binary_to_term(<<131,100,0,5,104,101,108,108,111>>, [safe]).</input> +> <input>binary_to_term(<<131,100,0,5,"hello">>, [safe]).</input> hello </pre> + </item> + <tag><c>used</c></tag> + <item> + <p>Changes the return value to <c>{Term, Used}</c> where <c>Used</c> + is the number of bytes actually read from <c>Binary</c>.</p> + <pre> +> <input>Input = <<131,100,0,5,"hello","world">>.</input> +<<131,100,0,5,104,101,108,108,111,119,111,114,108,100>> +> <input>{Term, Used} = binary_to_term(Input, [used]).</input> +{hello, 9} +> <input>split_binary(Input, Used).</input> +{<<131,100,0,5,104,101,108,108,111>>, <<"world">>} +</pre> + </item> + </taglist> + <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"><c>term_to_binary/1</c></seealso>, <seealso marker="#binary_to_term/1"> @@ -580,7 +613,7 @@ hello </func> <func> - <name name="bit_size" arity="1"/> + <name name="bit_size" arity="1" since=""/> <fsummary>Return the size of a bitstring.</fsummary> <desc> <p>Returns an integer that is the size in bits of @@ -595,7 +628,7 @@ hello </func> <func> - <name name="bitstring_to_list" arity="1"/> + <name name="bitstring_to_list" arity="1" since=""/> <fsummary>Convert a bitstring to a list.</fsummary> <desc> <p>Returns a list of integers corresponding to the bytes of @@ -606,7 +639,7 @@ hello </func> <func> - <name name="bump_reductions" arity="1"/> + <name name="bump_reductions" arity="1" since=""/> <fsummary>Increment the reduction counter.</fsummary> <desc> <p>This implementation-dependent function increments @@ -624,7 +657,7 @@ hello </func> <func> - <name name="byte_size" arity="1"/> + <name name="byte_size" arity="1" since=""/> <fsummary>Return the size of a bitstring (or binary).</fsummary> <desc> <p>Returns an integer that is the number of bytes needed to @@ -641,7 +674,7 @@ hello </func> <func> - <name name="cancel_timer" arity="1"/> + <name name="cancel_timer" arity="1" since=""/> <fsummary>Cancel a timer.</fsummary> <desc> <p>Cancels a timer. The same as calling @@ -651,7 +684,7 @@ hello </func> <func> - <name name="cancel_timer" arity="2"/> + <name name="cancel_timer" arity="2" since="OTP 18.0"/> <fsummary>Cancel a timer.</fsummary> <desc> <p>Cancels a timer that has been created by @@ -733,7 +766,20 @@ hello </func> <func> - <name name="check_old_code" arity="1"/> + <name name="ceil" arity="1" since="OTP 20.0"/> + <fsummary>Returns the smallest integer not less than the argument</fsummary> + <desc> + <p>Returns the smallest integer not less than + <c><anno>Number</anno></c>. + For example:</p> + <pre> +> <input>ceil(5.5).</input> +6</pre> + <p>Allowed in guard tests.</p> + </desc> + </func> + <func> + <name name="check_old_code" arity="1" since="OTP R14B04"/> <fsummary>Check if a module has old code.</fsummary> <desc> <p>Returns <c>true</c> if <c><anno>Module</anno></c> has old code, @@ -744,7 +790,7 @@ hello </func> <func> - <name name="check_process_code" arity="2"/> + <name name="check_process_code" arity="2" since=""/> <fsummary>Check if a process executes old code for a module.</fsummary> <desc> <p>The same as @@ -755,7 +801,7 @@ hello </func> <func> - <name name="check_process_code" arity="3"/> + <name name="check_process_code" arity="3" since="OTP 17.0"/> <fsummary>Check if a process executes old code for a module.</fsummary> <desc> <p>Checks if the node local process identified by @@ -858,7 +904,7 @@ hello </func> <func> - <name name="convert_time_unit" arity="3"/> + <name name="convert_time_unit" arity="3" since="OTP 18.0"/> <fsummary>Convert time unit of a time value.</fsummary> <desc> <p>Converts the <c><anno>Time</anno></c> value of time unit @@ -876,7 +922,7 @@ hello </func> <func> - <name name="crc32" arity="1"/> + <name name="crc32" arity="1" since=""/> <fsummary>Compute crc32 (IEEE 802.3) checksum.</fsummary> <desc> <p>Computes and returns the crc32 (IEEE 802.3 style) checksum @@ -885,7 +931,7 @@ hello </func> <func> - <name name="crc32" arity="2"/> + <name name="crc32" arity="2" since=""/> <fsummary>Compute crc32 (IEEE 802.3) checksum.</fsummary> <desc> <p>Continues computing the crc32 checksum by combining @@ -902,7 +948,7 @@ Y = erlang:crc32([Data1,Data2]).</code> </func> <func> - <name name="crc32_combine" arity="3"/> + <name name="crc32_combine" arity="3" since=""/> <fsummary>Combine two crc32 (IEEE 802.3) checksums.</fsummary> <desc> <p>Combines two previously computed crc32 checksums. @@ -921,7 +967,7 @@ Z = erlang:crc32_combine(X,Y,iolist_size(Data2)).</code> </func> <func> - <name name="date" arity="0"/> + <name name="date" arity="0" since=""/> <fsummary>Current date.</fsummary> <desc> <p>Returns the current date as <c>{Year, Month, Day}</c>.</p> @@ -934,7 +980,7 @@ Z = erlang:crc32_combine(X,Y,iolist_size(Data2)).</code> </func> <func> - <name name="decode_packet" arity="3"/> + <name name="decode_packet" arity="3" since=""/> <fsummary>Extract a protocol packet from a binary.</fsummary> <desc> <p>Decodes the binary <c><anno>Bin</anno></c> according to the packet @@ -1044,7 +1090,7 @@ Z = erlang:crc32_combine(X,Y,iolist_size(Data2)).</code> </func> <func> - <name name="delete_element" arity="2"/> + <name name="delete_element" arity="2" since="OTP R16B"/> <fsummary>Delete element at index in a tuple.</fsummary> <type_desc variable="Index">1..tuple_size(<anno>Tuple1</anno>)</type_desc> <desc> @@ -1057,7 +1103,7 @@ Z = erlang:crc32_combine(X,Y,iolist_size(Data2)).</code> </func> <func> - <name name="delete_module" arity="1"/> + <name name="delete_module" arity="1" since=""/> <fsummary>Make the current code for a module old.</fsummary> <desc> <p>Makes the current code for <c><anno>Module</anno></c> become old @@ -1075,7 +1121,7 @@ Z = erlang:crc32_combine(X,Y,iolist_size(Data2)).</code> </func> <func> - <name name="demonitor" arity="1"/> + <name name="demonitor" arity="1" since=""/> <fsummary>Stop monitoring.</fsummary> <desc> <p>If <c><anno>MonitorRef</anno></c> is a reference that the @@ -1117,7 +1163,7 @@ Z = erlang:crc32_combine(X,Y,iolist_size(Data2)).</code> </func> <func> - <name name="demonitor" arity="2"/> + <name name="demonitor" arity="2" since=""/> <fsummary>Stop monitoring.</fsummary> <desc> <p>The returned value is <c>true</c> unless <c>info</c> is part @@ -1185,7 +1231,7 @@ end</code> </func> <func> - <name name="disconnect_node" arity="1"/> + <name name="disconnect_node" arity="1" since=""/> <fsummary>Force the disconnection of a node.</fsummary> <desc> <p>Forces the disconnection of a node. This appears to @@ -1199,7 +1245,7 @@ end</code> </func> <func> - <name name="display" arity="1"/> + <name name="display" arity="1" since=""/> <fsummary>Print a term on standard output.</fsummary> <desc> <p>Prints a text representation of <c><anno>Term</anno></c> on the @@ -1211,7 +1257,142 @@ end</code> </func> <func> - <name name="element" arity="2"/> + <name name="dist_ctrl_get_data" arity="1" since="OTP 21.0"/> + <fsummary>Get distribution channel data to pass to another node.</fsummary> + <desc> + <p> + Get distribution channel data from the local node that is + to be passed to the remote node. The distribution channel + is identified by <c><anno>DHandle</anno></c>. If no data + is available, the atom <c>none</c> is returned. One + can request to be informed by a message when more + data is available by calling + <seealso marker="erlang#dist_ctrl_get_data_notification/1"><c>erlang:dist_ctrl_get_data_notification(DHandle)</c></seealso>. + </p> + <note><p> + Only the process registered as distribution + controller for the distribution channel identified by + <c><anno>DHandle</anno></c> is allowed to call this + function. + </p></note> + <p> + This function is used when implementing an alternative + distribution carrier using processes as distribution + controllers. <c><anno>DHandle</anno></c> is retrived + via the callback + <seealso marker="erts:alt_dist#hs_data_f_handshake_complete"><c>f_handshake_complete</c></seealso>. + More information can be found in the documentation of + <seealso marker="erts:alt_dist#distribution_module">ERTS + User's Guide ➜ How to implement an Alternative Carrier + for the Erlang Distribution ➜ Distribution Module</seealso>. + </p> + </desc> + </func> + + <func> + <name name="dist_ctrl_get_data_notification" arity="1" since="OTP 21.0"/> + <fsummary>Request notification about available outgoing distribution channel data.</fsummary> + <desc> + <p> + Request notification when more data is available to + fetch using + <seealso marker="erlang#dist_ctrl_get_data/1"><c>erlang:dist_ctrl_get_data(DHandle)</c></seealso> + for the distribution channel identified by + <c><anno>DHandle</anno></c>. When more data is present, + the caller will be sent the message <c>dist_data</c>. + Once a <c>dist_data</c> messages has been sent, no + more <c>dist_data</c> messages will be sent until + the <c>dist_ctrl_get_data_notification/1</c> function has been called + again. + </p> + <note><p> + Only the process registered as distribution + controller for the distribution channel identified by + <c><anno>DHandle</anno></c> is allowed to call this + function. + </p></note> + <p> + This function is used when implementing an alternative + distribution carrier using processes as distribution + controllers. <c><anno>DHandle</anno></c> is retrived + via the callback + <seealso marker="erts:alt_dist#hs_data_f_handshake_complete"><c>f_handshake_complete</c></seealso>. + More information can be found in the documentation of + <seealso marker="erts:alt_dist#distribution_module">ERTS + User's Guide ➜ How to implement an Alternative Carrier + for the Erlang Distribution ➜ Distribution Module</seealso>. + </p> + </desc> + </func> + + <func> + <name name="dist_ctrl_input_handler" arity="2" since="OTP 21.0"/> + <fsummary>Register distribution channel input handler process.</fsummary> + <desc> + <p> + Register an alternate input handler process for the + distribution channel identified by <c><anno>DHandle</anno></c>. + Once this function has been called, <c><anno>InputHandler</anno></c> + is the only process allowed to call + <seealso marker="erlang#dist_ctrl_put_data/2"><c>erlang:dist_ctrl_put_data(DHandle, Data)</c></seealso> + with the <c><anno>DHandle</anno></c> identifing this distribution + channel. + </p> + <note><p> + Only the process registered as distribution + controller for the distribution channel identified by + <c><anno>DHandle</anno></c> is allowed to call this + function. + </p></note> + <p> + This function is used when implementing an alternative + distribution carrier using processes as distribution + controllers. <c><anno>DHandle</anno></c> is retrived + via the callback + <seealso marker="erts:alt_dist#hs_data_f_handshake_complete"><c>f_handshake_complete</c></seealso>. + More information can be found in the documentation of + <seealso marker="erts:alt_dist#distribution_module">ERTS + User's Guide ➜ How to implement an Alternative Carrier + for the Erlang Distribution ➜ Distribution Module</seealso>. + </p> + </desc> + </func> + + <func> + <name name="dist_ctrl_put_data" arity="2" since="OTP 21.0"/> + <fsummary>Pass data into the VM from a distribution channel.</fsummary> + <desc> + <p> + Deliver distribution channel data from a remote node to the + local node. + </p> + <note><p> + Only the process registered as distribution + controller for the distribution channel identified by + <c><anno>DHandle</anno></c> is allowed to call this + function unless an alternate input handler process + has been registered using + <seealso marker="erlang#dist_ctrl_input_handler/2"><c>erlang:dist_ctrl_input_handler(DHandle, InputHandler)</c></seealso>. + If an alternate input handler has been registered, only + the registered input handler process is allowed to call + this function. + </p></note> + <p> + This function is used when implementing an alternative + distribution carrier using processes as distribution + controllers. <c><anno>DHandle</anno></c> is retrived + via the callback + <seealso marker="erts:alt_dist#hs_data_f_handshake_complete"><c>f_handshake_complete</c></seealso>. + More information can be found in the documentation of + <seealso marker="erts:alt_dist#distribution_module">ERTS + User's Guide ➜ How to implement an Alternative Carrier + for the Erlang Distribution ➜ Distribution Module</seealso>. + </p> + </desc> + </func> + + <func> + <name name="element" arity="2" since=""/> <fsummary>Return the Nth element of a tuple.</fsummary> <type_desc variable="N">1..tuple_size(<anno>Tuple</anno>)</type_desc> <desc> @@ -1225,7 +1406,7 @@ b</pre> </func> <func> - <name name="erase" arity="0"/> + <name name="erase" arity="0" since=""/> <fsummary>Return and delete the process dictionary.</fsummary> <desc> <p>Returns the process dictionary and deletes it, for @@ -1239,7 +1420,7 @@ b</pre> </func> <func> - <name name="erase" arity="1"/> + <name name="erase" arity="1" since=""/> <fsummary>Return and delete a value from the process dictionary. </fsummary> <desc> @@ -1256,7 +1437,7 @@ b</pre> </func> <func> - <name name="error" arity="1"/> + <name name="error" arity="1" since=""/> <fsummary>Stop execution with a specified reason.</fsummary> <desc> <p>Stops the execution of the calling process with the reason @@ -1268,16 +1449,19 @@ b</pre> the process to terminate, it has no return value. Example:</p> <pre> > <input>catch error(foobar).</input> -{'EXIT',{foobar,[{erl_eval,do_apply,5}, - {erl_eval,expr,5}, - {shell,exprs,6}, - {shell,eval_exprs,6}, - {shell,eval_loop,3}]}}</pre> +{'EXIT',{foobar,[{shell,apply_fun,3, + [{file,"shell.erl"},{line,906}]}, + {erl_eval,do_apply,6,[{file,"erl_eval.erl"},{line,677}]}, + {erl_eval,expr,5,[{file,"erl_eval.erl"},{line,430}]}, + {shell,exprs,7,[{file,"shell.erl"},{line,687}]}, + {shell,eval_exprs,7,[{file,"shell.erl"},{line,642}]}, + {shell,eval_loop,3,[{file,"shell.erl"},{line,627}]}]}} +</pre> </desc> </func> <func> - <name name="error" arity="2"/> + <name name="error" arity="2" since=""/> <fsummary>Stop execution with a specified reason.</fsummary> <desc> <p>Stops the execution of the calling process with the reason @@ -1294,7 +1478,7 @@ b</pre> </func> <func> - <name name="exit" arity="1"/> + <name name="exit" arity="1" since=""/> <fsummary>Stop execution with a specified reason.</fsummary> <desc> <p>Stops the execution of the calling process with exit reason @@ -1311,7 +1495,7 @@ b</pre> </func> <func> - <name name="exit" arity="2"/> + <name name="exit" arity="2" since=""/> <fsummary>Send 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 @@ -1347,7 +1531,7 @@ b</pre> </func> <func> - <name name="external_size" arity="1"/> + <name name="external_size" arity="1" since="OTP R14B04"/> <fsummary>Calculate the maximum size for a term encoded in the Erlang external term format.</fsummary> <desc> @@ -1366,7 +1550,7 @@ erlang:external_size(<anno>Term</anno>, [])</code> </func> <func> - <name name="external_size" arity="2"/> + <name name="external_size" arity="2" since="OTP R14B04"/> <fsummary>Calculate the maximum size for a term encoded in the Erlang external term format.</fsummary> <desc> @@ -1386,7 +1570,7 @@ true</pre> </func> <func> - <name name="float" arity="1"/> + <name name="float" arity="1" since=""/> <fsummary>Convert a number to a float.</fsummary> <desc> <p>Returns a float by converting <c><anno>Number</anno></c> to a float, @@ -1408,7 +1592,7 @@ true</pre> </func> <func> - <name name="float_to_binary" arity="1"/> + <name name="float_to_binary" arity="1" since="OTP R16B"/> <fsummary>Text representation of a float.</fsummary> <desc> <p>The same as @@ -1417,7 +1601,7 @@ true</pre> </func> <func> - <name name="float_to_binary" arity="2"/> + <name name="float_to_binary" arity="2" since="OTP R16B"/> <fsummary>Text representation of a float formatted using specified options.</fsummary> <desc> @@ -1435,7 +1619,7 @@ true</pre> </func> <func> - <name name="float_to_list" arity="1"/> + <name name="float_to_list" arity="1" since=""/> <fsummary>Text representation of a float.</fsummary> <desc> <p>The same as @@ -1444,7 +1628,7 @@ true</pre> </func> <func> - <name name="float_to_list" arity="2"/> + <name name="float_to_list" arity="2" since="OTP R16B"/> <fsummary>Text representation of a float formatted using specified options.</fsummary> <desc> @@ -1480,7 +1664,21 @@ true</pre> </func> <func> - <name name="fun_info" arity="1"/> + <name name="floor" arity="1" since="OTP 20.0"/> + <fsummary>Returns the largest integer not greater than the argument</fsummary> + <desc> + <p>Returns the largest integer not greater than + <c><anno>Number</anno></c>. + For example:</p> + <pre> +> <input>floor(-10.5).</input> +-11</pre> + <p>Allowed in guard tests.</p> + </desc> + </func> + + <func> + <name name="fun_info" arity="1" since=""/> <fsummary>Information about a fun.</fsummary> <desc> <p>Returns a list with information about the fun @@ -1581,7 +1779,7 @@ true</pre> </func> <func> - <name name="fun_info" arity="2"/> + <name name="fun_info" arity="2" since=""/> <fsummary>Information about a fun.</fsummary> <type name="fun_info_item"/> <desc> @@ -1601,7 +1799,7 @@ true</pre> </func> <func> - <name name="fun_to_list" arity="1"/> + <name name="fun_to_list" arity="1" since=""/> <fsummary>Text representation of a fun.</fsummary> <desc> <p>Returns a string corresponding to the text @@ -1610,7 +1808,7 @@ true</pre> </func> <func> - <name name="function_exported" arity="3"/> + <name name="function_exported" arity="3" since=""/> <fsummary>Check if a function is exported and loaded.</fsummary> <desc> <p>Returns <c>true</c> if the module <c><anno>Module</anno></c> is @@ -1626,7 +1824,7 @@ true</pre> </func> <func> - <name name="garbage_collect" arity="0"/> + <name name="garbage_collect" arity="0" since=""/> <fsummary>Force an immediate garbage collection of the calling process. </fsummary> <desc> @@ -1642,7 +1840,7 @@ true</pre> </func> <func> - <name name="garbage_collect" arity="1"/> + <name name="garbage_collect" arity="1" since=""/> <fsummary>Garbage collect a process.</fsummary> <desc> <p>The same as @@ -1652,7 +1850,7 @@ true</pre> </func> <func> - <name name="garbage_collect" arity="2"/> + <name name="garbage_collect" arity="2" since="OTP 17.0"/> <fsummary>Garbage collect a process.</fsummary> <desc> <p>Garbage collects the node local process identified by @@ -1667,6 +1865,12 @@ true</pre> the form <c>{garbage_collect, <anno>RequestId</anno>, <anno>GCResult</anno>}</c>. </item> + + <tag><c>{type, 'major' | 'minor'}</c></tag> + <item>Triggers garbage collection of requested type. Default value is + <c>'major'</c>, which would trigger a fullsweep GC. + The option <c>'minor'</c> is considered a hint and may lead to + either minor or major GC run.</item> </taglist> <p>If <c><anno>Pid</anno></c> equals <c>self()</c>, and no <c>async</c> option has been passed, the garbage @@ -1711,7 +1915,7 @@ true</pre> </func> <func> - <name name="get" arity="0"/> + <name name="get" arity="0" since=""/> <fsummary>Return the process dictionary.</fsummary> <desc> <p>Returns the process dictionary as a list of @@ -1726,7 +1930,7 @@ true</pre> </func> <func> - <name name="get" arity="1"/> + <name name="get" arity="1" since=""/> <fsummary>Return a value from the process dictionary.</fsummary> <desc> <p>Returns the value <c><anno>Val</anno></c> associated with @@ -1742,7 +1946,7 @@ true</pre> </func> <func> - <name name="get_cookie" arity="0"/> + <name name="get_cookie" arity="0" since=""/> <fsummary>Get the magic cookie of the local node.</fsummary> <desc> <p>Returns the magic cookie of the local node if the node is @@ -1751,7 +1955,7 @@ true</pre> </func> <func> - <name name="get_keys" arity="0"/> + <name name="get_keys" arity="0" since="OTP 18.0"/> <fsummary>Return a list of all keys from the process dictionary. </fsummary> <desc> @@ -1767,7 +1971,7 @@ true</pre> </func> <func> - <name name="get_keys" arity="1"/> + <name name="get_keys" arity="1" since=""/> <fsummary>Return a list of keys from the process dictionary.</fsummary> <desc> <p>Returns a list of keys that are associated with the value @@ -1785,16 +1989,27 @@ true</pre> </func> <func> - <name name="get_stacktrace" arity="0"/> + <name name="get_stacktrace" arity="0" since=""/> <fsummary>Get the call stack back-trace of the last exception.</fsummary> <type name="stack_item"/> <desc> - <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. 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> + <warning><p><c>erlang:get_stacktrace/0</c> is deprecated and will stop working + in a future release.</p></warning> + <p>Instead of using <c>erlang:get_stacktrace/0</c> to retrieve + the call stack back-trace, use the following syntax:</p> +<pre> +try Expr +catch + Class:Reason:Stacktrace -> + {Class,Reason,Stacktrace} +end</pre> + <p><c>erlang:get_stacktrace/0</c> retrieves the call stack back-trace + (<em>stacktrace</em>) for an exception that has just been + caught in the calling process as a list of + <c>{<anno>Module</anno>,<anno>Function</anno>,<anno>Arity</anno>,<anno>Location</anno>}</c> + tuples. 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 can also be reset to <c>[]</c>.</p> @@ -1820,6 +2035,18 @@ true</pre> where the exception occurred or the function was called. </item> </taglist> + <warning><p>Developers should rely on stacktrace entries only for + debugging purposes.</p> + <p>The VM performs tail call optimization, which + does not add new entries to the stacktrace, and also limits stacktraces + to a certain depth. Furthermore, compiler options, optimizations and + future changes may add or remove stacktrace entries, causing any code + that expects the stacktrace to be in a certain order or contain specific + items to fail.</p> + <p>The only exception to this rule is <c>error:undef</c> which + guarantees to include the <anno>Module</anno>, <anno>Function</anno> and <anno>Arity</anno> + of the attempted function as the first stacktrace entry.</p> + </warning> <p>See also <seealso marker="#error/1"><c>error/1</c></seealso> and <seealso marker="#error/2"><c>error/2</c></seealso>.</p> @@ -1827,7 +2054,7 @@ true</pre> </func> <func> - <name name="group_leader" arity="0"/> + <name name="group_leader" arity="0" since=""/> <fsummary>Get the group leader for the calling process.</fsummary> <desc> <p>Returns the process identifier of the group leader for the @@ -1842,7 +2069,7 @@ true</pre> </func> <func> - <name name="group_leader" arity="2"/> + <name name="group_leader" arity="2" since=""/> <fsummary>Set the group leader for a process.</fsummary> <desc> <p>Sets the group leader of <c><anno>Pid</anno></c> @@ -1850,13 +2077,20 @@ true</pre> Typically, this is used when a process started from a certain shell is to have another group leader than <c>init</c>.</p> + <p>The group leader should be rarely changed in + applications with a supervision tree, because OTP + assumes the group leader of their processes is + their application master.</p> <p>See also - <seealso marker="#group_leader/0"><c>group_leader/0</c></seealso>.</p> + <seealso marker="#group_leader/0"><c>group_leader/0</c></seealso> + and <seealso marker="doc/design_principles:applications#stopping">OTP + design principles</seealso> related to starting and stopping + applications.</p> </desc> </func> <func> - <name name="halt" arity="0"/> + <name name="halt" arity="0" since=""/> <fsummary>Halt the Erlang runtime system and indicate normal exit to the calling environment.</fsummary> <desc> @@ -1869,7 +2103,7 @@ os_prompt%</pre> </func> <func> - <name name="halt" arity="1"/> + <name name="halt" arity="1" since=""/> <fsummary>Halt the Erlang runtime system.</fsummary> <desc> <p>The same as <seealso marker="#halt/2"> @@ -1883,7 +2117,7 @@ os_prompt%</pre> </func> <func> - <name name="halt" arity="2"/> + <name name="halt" arity="2" since="OTP R15B01"/> <fsummary>Halt the Erlang runtime system.</fsummary> <desc> <p><c><anno>Status</anno></c> must be a non-negative integer, a string, @@ -1895,23 +2129,26 @@ os_prompt%</pre> <item>The runtime system exits with integer value <c><anno>Status</anno></c> as status code to the calling environment (OS). + <note> + <p>On many platforms, the OS supports only status + codes 0-255. A too large status code is truncated by clearing + the high bits.</p> + </note> </item> <tag>string()</tag> <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. + The string will be truncated if longer than 200 characters. + <note> + <p>Before ERTS 9.1 (OTP-20.1) only code points in the range 0-255 + was accepted in the string. Now any unicode string is valid.</p> + </note> </item> <tag><c>abort</c></tag> <item>The runtime system aborts producing a core dump, if that is enabled in the OS. </item> </taglist> - <note> - <p>On many platforms, the OS supports only status - codes 0-255. A too large status code is 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 @@ -1922,27 +2159,7 @@ os_prompt%</pre> </func> <func> - <name name="hash" arity="2"/> - <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 maximum range is 1..2^27-1.</p> - <warning> - <p><em>This BIF is deprecated, as the hash value can differ on - different architectures.</em> The hash values for integer - terms > 2^27 and large binaries are - poor. The BIF is retained for backward compatibility - reasons (it can have been used to hash records into a file), - but all new code is to use one of the BIFs - <seealso marker="#phash/2"><c>erlang:phash/2</c></seealso> or - <seealso marker="#phash2/1"><c>erlang:phash2/1,2</c></seealso> - instead.</p> - </warning> - </desc> - </func> - - <func> - <name name="hd" arity="1"/> + <name name="hd" arity="1" since=""/> <fsummary>Head of a list.</fsummary> <desc> <p>Returns the head of <c><anno>List</anno></c>, that is, @@ -1957,7 +2174,7 @@ os_prompt%</pre> </func> <func> - <name name="hibernate" arity="3"/> + <name name="hibernate" arity="3" since=""/> <fsummary>Hibernate a process until a message is sent to it.</fsummary> <desc> <p>Puts the calling process into a wait state where its memory @@ -1998,7 +2215,7 @@ os_prompt%</pre> </func> <func> - <name name="insert_element" arity="3"/> + <name name="insert_element" arity="3" since="OTP R16B"/> <fsummary>Insert an element at index in a tuple.</fsummary> <type_desc variable="Index">1..tuple_size(<anno>Tuple1</anno>) + 1</type_desc> @@ -2016,7 +2233,7 @@ os_prompt%</pre> </func> <func> - <name name="integer_to_binary" arity="1"/> + <name name="integer_to_binary" arity="1" since="OTP R16B"/> <fsummary>Text representation of an integer.</fsummary> <desc> <p>Returns a binary corresponding to the text @@ -2028,7 +2245,7 @@ os_prompt%</pre> </func> <func> - <name name="integer_to_binary" arity="2"/> + <name name="integer_to_binary" arity="2" since="OTP R16B"/> <fsummary>Text representation of an integer.</fsummary> <desc> <p>Returns a binary corresponding to the text @@ -2041,7 +2258,7 @@ os_prompt%</pre> </func> <func> - <name name="integer_to_list" arity="1"/> + <name name="integer_to_list" arity="1" since=""/> <fsummary>Text representation of an integer.</fsummary> <desc> <p>Returns a string corresponding to the text @@ -2053,7 +2270,7 @@ os_prompt%</pre> </func> <func> - <name name="integer_to_list" arity="2"/> + <name name="integer_to_list" arity="2" since=""/> <fsummary>Text representation of an integer.</fsummary> <desc> <p>Returns a string corresponding to the text @@ -2066,7 +2283,7 @@ os_prompt%</pre> </func> <func> - <name name="iolist_size" arity="1"/> + <name name="iolist_size" arity="1" since=""/> <fsummary>Size of an iolist.</fsummary> <desc> <p>Returns an integer, that is the size in bytes, @@ -2079,7 +2296,7 @@ os_prompt%</pre> </func> <func> - <name name="iolist_to_binary" arity="1"/> + <name name="iolist_to_binary" arity="1" since=""/> <fsummary>Convert an iolist to a binary.</fsummary> <desc> <p>Returns a binary that is made from the integers and @@ -2097,7 +2314,16 @@ os_prompt%</pre> </func> <func> - <name name="is_alive" arity="0"/> + <name name="iolist_to_iovec" arity="1" since="OTP 20.1"/> + <fsummary>Converts an iolist to a iovec.</fsummary> + <desc> + <p>Returns an iovec that is made from the integers and binaries in + <c><anno>IoListOrBinary</anno></c>.</p> + </desc> + </func> + + <func> + <name name="is_alive" arity="0" since=""/> <fsummary>Check whether the local node is alive.</fsummary> <desc> <p>Returns <c>true</c> if the local node is alive (that is, if @@ -2107,7 +2333,7 @@ os_prompt%</pre> </func> <func> - <name name="is_atom" arity="1"/> + <name name="is_atom" arity="1" since=""/> <fsummary>Check whether a term is an atom.</fsummary> <desc> <p>Returns <c>true</c> if <c><anno>Term</anno></c> is an atom, @@ -2117,7 +2343,7 @@ os_prompt%</pre> </func> <func> - <name name="is_binary" arity="1"/> + <name name="is_binary" arity="1" since=""/> <fsummary>Check whether a term is a binary.</fsummary> <desc> <p>Returns <c>true</c> if <c><anno>Term</anno></c> is a binary, @@ -2128,7 +2354,7 @@ os_prompt%</pre> </func> <func> - <name name="is_bitstring" arity="1"/> + <name name="is_bitstring" arity="1" since=""/> <fsummary>Check whether a term is a bitstring.</fsummary> <desc> <p>Returns <c>true</c> if <c><anno>Term</anno></c> is a @@ -2138,7 +2364,7 @@ os_prompt%</pre> </func> <func> - <name name="is_boolean" arity="1"/> + <name name="is_boolean" arity="1" since=""/> <fsummary>Check whether a term is a boolean.</fsummary> <desc> <p>Returns <c>true</c> if <c><anno>Term</anno></c> is the @@ -2149,7 +2375,7 @@ os_prompt%</pre> </func> <func> - <name name="is_builtin" arity="3"/> + <name name="is_builtin" arity="3" since=""/> <fsummary>Check if a function is a BIF implemented in C.</fsummary> <desc> <p>This BIF is useful for builders of cross-reference tools.</p> @@ -2160,7 +2386,7 @@ os_prompt%</pre> </func> <func> - <name name="is_float" arity="1"/> + <name name="is_float" arity="1" since=""/> <fsummary>Check whether a term is a float.</fsummary> <desc> <p>Returns <c>true</c> if <c><anno>Term</anno></c> is a floating point @@ -2170,7 +2396,7 @@ os_prompt%</pre> </func> <func> - <name name="is_function" arity="1"/> + <name name="is_function" arity="1" since=""/> <fsummary>Check whether a term is a fun.</fsummary> <desc> <p>Returns <c>true</c> if <c><anno>Term</anno></c> is a fun, otherwise @@ -2180,7 +2406,7 @@ os_prompt%</pre> </func> <func> - <name name="is_function" arity="2"/> + <name name="is_function" arity="2" since=""/> <fsummary>Check whether a term is a fun with a specified given arity. </fsummary> <desc> @@ -2192,7 +2418,7 @@ os_prompt%</pre> </func> <func> - <name name="is_integer" arity="1"/> + <name name="is_integer" arity="1" since=""/> <fsummary>Check whether a term is an integer.</fsummary> <desc> <p>Returns <c>true</c> if <c><anno>Term</anno></c> is an integer, @@ -2202,7 +2428,7 @@ os_prompt%</pre> </func> <func> - <name name="is_list" arity="1"/> + <name name="is_list" arity="1" since=""/> <fsummary>Check whether a term is a list.</fsummary> <desc> <p>Returns <c>true</c> if <c><anno>Term</anno></c> is a list with @@ -2212,7 +2438,7 @@ os_prompt%</pre> </func> <func> - <name name="is_map" arity="1"/> + <name name="is_map" arity="1" since="OTP 17.0"/> <fsummary>Check whether a term is a map.</fsummary> <desc> <p>Returns <c>true</c> if <c><anno>Term</anno></c> is a map, @@ -2222,7 +2448,27 @@ os_prompt%</pre> </func> <func> - <name name="is_number" arity="1"/> + <name name="is_map_key" arity="2" since="OTP 21.0"/> + <fsummary></fsummary> + <desc> + <p>Returns <c>true</c> if map <c><anno>Map</anno></c> contains + <c><anno>Key</anno></c> and returns <c>false</c> if it does not + contain the <c><anno>Key</anno></c>.</p> + <p>The call fails with a <c>{badmap,Map}</c> exception if + <c><anno>Map</anno></c> is not a map.</p> + <p><em>Example:</em></p> + <code type="none"> +> Map = #{"42" => value}. +#{"42" => value} +> is_map_key("42",Map). +true +> is_map_key(value,Map). +false</code> + </desc> + </func> + + <func> + <name name="is_number" arity="1" since=""/> <fsummary>Check whether a term is a number.</fsummary> <desc> <p>Returns <c>true</c> if <c><anno>Term</anno></c> is an integer or a @@ -2232,7 +2478,7 @@ os_prompt%</pre> </func> <func> - <name name="is_pid" arity="1"/> + <name name="is_pid" arity="1" since=""/> <fsummary>Check whether a term is a process identifier.</fsummary> <desc> <p>Returns <c>true</c> if <c><anno>Term</anno></c> is a process @@ -2242,7 +2488,7 @@ os_prompt%</pre> </func> <func> - <name name="is_port" arity="1"/> + <name name="is_port" arity="1" since=""/> <fsummary>Check whether a term is a port.</fsummary> <desc> <p>Returns <c>true</c> if <c><anno>Term</anno></c> is a port identifier, @@ -2252,7 +2498,7 @@ os_prompt%</pre> </func> <func> - <name name="is_process_alive" arity="1"/> + <name name="is_process_alive" arity="1" since=""/> <fsummary>Check whether a process is alive.</fsummary> <desc> <p><c><anno>Pid</anno></c> must refer to a process at the local @@ -2264,7 +2510,7 @@ os_prompt%</pre> </func> <func> - <name name="is_record" arity="2"/> + <name name="is_record" arity="2" since=""/> <fsummary>Check 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 @@ -2285,7 +2531,7 @@ os_prompt%</pre> </func> <func> - <name name="is_record" arity="3"/> + <name name="is_record" arity="3" since=""/> <fsummary>Check whether a term appears to be a record.</fsummary> <desc> <p><c><anno>RecordTag</anno></c> must be an atom.</p> @@ -2304,7 +2550,7 @@ os_prompt%</pre> </func> <func> - <name name="is_reference" arity="1"/> + <name name="is_reference" arity="1" since=""/> <fsummary>Check whether a term is a reference.</fsummary> <desc> <p>Returns <c>true</c> if <c><anno>Term</anno></c> is a reference, @@ -2314,7 +2560,7 @@ os_prompt%</pre> </func> <func> - <name name="is_tuple" arity="1"/> + <name name="is_tuple" arity="1" since=""/> <fsummary>Check whether a term is a tuple.</fsummary> <desc> <p>Returns <c>true</c> if <c><anno>Term</anno></c> is a tuple, @@ -2324,7 +2570,7 @@ os_prompt%</pre> </func> <func> - <name name="length" arity="1"/> + <name name="length" arity="1" since=""/> <fsummary>Length of a list.</fsummary> <desc> <p>Returns the length of <c><anno>List</anno></c>, for example:</p> @@ -2336,7 +2582,7 @@ os_prompt%</pre> </func> <func> - <name name="link" arity="1"/> + <name name="link" arity="1" since=""/> <fsummary>Create a link to another process (or port).</fsummary> <desc> <p>Creates a link between the calling process and another @@ -2363,15 +2609,15 @@ os_prompt%</pre> </func> <func> - <name name="list_to_atom" arity="1"/> + <name name="list_to_atom" arity="1" since=""/> <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> can only contain ISO-latin-1 - characters (that is, numbers < 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 + <p>As from Erlang/OTP 20, <c><anno>String</anno></c> may contain + any Unicode character. Earlier versions allowed only ISO-latin-1 + characters as the implementation did not allow Unicode characters + above 255. 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> @@ -2383,7 +2629,7 @@ os_prompt%</pre> </func> <func> - <name name="list_to_binary" arity="1"/> + <name name="list_to_binary" arity="1" since=""/> <fsummary>Convert a list to a binary.</fsummary> <desc> <p>Returns a binary that is made from the integers and @@ -2401,7 +2647,7 @@ os_prompt%</pre> </func> <func> - <name name="list_to_bitstring" arity="1"/> + <name name="list_to_bitstring" arity="1" since=""/> <fsummary>Convert a list to a bitstring.</fsummary> <type name="bitstring_list"/> <desc> @@ -2422,7 +2668,7 @@ os_prompt%</pre> </func> <func> - <name name="list_to_existing_atom" arity="1"/> + <name name="list_to_existing_atom" arity="1" since=""/> <fsummary>Convert from text representation to an atom.</fsummary> <desc> <p>Returns the atom whose text representation is @@ -2430,11 +2676,20 @@ os_prompt%</pre> 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> + <note> + <p>Note that the compiler may optimize away atoms. For + example, the compiler will rewrite + <c>atom_to_list(some_atom)</c> to <c>"some_atom"</c>. If + that expression is the only mention of the atom + <c>some_atom</c> in the containing module, the atom will not + be created when the module is loaded, and a subsequent call + to <c>list_to_existing_atom("some_atom")</c> will fail.</p> + </note> </desc> </func> <func> - <name name="list_to_float" arity="1"/> + <name name="list_to_float" arity="1" since=""/> <fsummary>Convert from text representation to a float.</fsummary> <desc> <p>Returns the float whose text representation is @@ -2448,7 +2703,7 @@ os_prompt%</pre> </func> <func> - <name name="list_to_integer" arity="1"/> + <name name="list_to_integer" arity="1" since=""/> <fsummary>Convert from text representation to an integer.</fsummary> <desc> <p>Returns an integer whose text representation is @@ -2462,7 +2717,7 @@ os_prompt%</pre> </func> <func> - <name name="list_to_integer" arity="2"/> + <name name="list_to_integer" arity="2" since=""/> <fsummary>Convert from text representation to an integer.</fsummary> <desc> <p>Returns an integer whose text representation in base @@ -2477,7 +2732,7 @@ os_prompt%</pre> </func> <func> - <name name="list_to_pid" arity="1"/> + <name name="list_to_pid" arity="1" since=""/> <fsummary>Convert from text representation to a pid.</fsummary> <desc> <p>Returns a process identifier whose text representation is a @@ -2495,7 +2750,43 @@ os_prompt%</pre> </func> <func> - <name name="list_to_tuple" arity="1"/> + <name name="list_to_port" arity="1" since="OTP 20.0"/> + <fsummary>Convert from text representation to a port.</fsummary> + <desc> + <p>Returns a port identifier whose text representation is a + <c><anno>String</anno></c>, for example:</p> + <pre> +> <input>list_to_port("#Port<0.4>").</input> +#Port<0.4></pre> + <p>Failure: <c>badarg</c> if <c><anno>String</anno></c> contains a bad + representation of a port 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_ref" arity="1" since="OTP 20.0"/> + <fsummary>Convert from text representation to a ref.</fsummary> + <desc> + <p>Returns a reference whose text representation is a + <c><anno>String</anno></c>, for example:</p> + <pre> +> <input>list_to_ref("#Ref<0.4192537678.4073193475.71181>").</input> +#Ref<0.4192537678.4073193475.71181></pre> + <p>Failure: <c>badarg</c> if <c><anno>String</anno></c> contains a bad + representation of a reference.</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" since=""/> <fsummary>Convert a list to a tuple.</fsummary> <desc> <p>Returns a tuple corresponding to <c><anno>List</anno></c>, @@ -2508,7 +2799,7 @@ os_prompt%</pre> </func> <func> - <name name="load_module" arity="2"/> + <name name="load_module" arity="2" since=""/> <fsummary>Load object code for a module.</fsummary> <desc> <p>If <c><anno>Binary</anno></c> contains the object code for module @@ -2541,16 +2832,9 @@ os_prompt%</pre> </func> <func> - <name name="load_nif" arity="2"/> + <name name="load_nif" arity="2" since=""/> <fsummary>Load NIF library.</fsummary> <desc> - <note> - <p>Before Erlang/OTP R14B, NIFs were an - experimental feature. Versions before Erlang/OTP R14B can - have different and possibly incompatible NIF semantics and - interfaces. For example, in Erlang/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 shareable object/dynamic library file minus @@ -2580,20 +2864,28 @@ os_prompt%</pre> <item>The library did not fulfill the requirements as a NIF library of the calling module. </item> - <tag><c>load | reload | upgrade</c></tag> + <tag><c>load | upgrade</c></tag> <item>The corresponding library callback was unsuccessful. </item> + <tag><c>reload</c></tag> + <item>A NIF library is already loaded for this module instance. + The previously deprecated <c>reload</c> feature was removed in OTP 20. + </item> <tag><c>old_code</c></tag> <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> + <tag><c>notsup</c></tag> + <item>Lack of support. Such as loading NIF library for a + HiPE compiled module. + </item> </taglist> </desc> </func> <func> - <name name="loaded" arity="0"/> + <name name="loaded" arity="0" since=""/> <fsummary>List all loaded modules.</fsummary> <desc> <p>Returns a list of all loaded Erlang modules (current and @@ -2604,7 +2896,7 @@ os_prompt%</pre> </func> <func> - <name name="localtime" arity="0"/> + <name name="localtime" arity="0" since=""/> <fsummary>Current local date and time.</fsummary> <desc> <p>Returns the current local date and time, @@ -2619,7 +2911,7 @@ os_prompt%</pre> </func> <func> - <name name="localtime_to_universaltime" arity="1"/> + <name name="localtime_to_universaltime" arity="1" since=""/> <fsummary>Convert from local to Universal Time Coordinated (UTC) date and time.</fsummary> <desc> @@ -2636,7 +2928,7 @@ os_prompt%</pre> </func> <func> - <name name="localtime_to_universaltime" arity="2"/> + <name name="localtime_to_universaltime" arity="2" since=""/> <fsummary>Convert from local to Universal Time Coordinated (UTC) date and time.</fsummary> <desc> @@ -2662,7 +2954,7 @@ os_prompt%</pre> </func> <func> - <name name="make_ref" arity="0"/> + <name name="make_ref" arity="0" since=""/> <fsummary>Return a unique reference.</fsummary> <desc> <p>Returns a @@ -2679,7 +2971,7 @@ os_prompt%</pre> </func> <func> - <name name="make_tuple" arity="2"/> + <name name="make_tuple" arity="2" since=""/> <fsummary>Create a new tuple of a specified arity.</fsummary> <desc> <p>Creates a new tuple of the specified <c><anno>Arity</anno></c>, where @@ -2691,7 +2983,7 @@ os_prompt%</pre> </func> <func> - <name name="make_tuple" arity="3"/> + <name name="make_tuple" arity="3" since=""/> <fsummary>Create a new tuple with specifed arity and contents.</fsummary> <desc> <p>Creates a tuple of size <c><anno>Arity</anno></c>, where each element @@ -2709,7 +3001,26 @@ os_prompt%</pre> </func> <func> - <name name="map_size" arity="1"/> + <name name="map_get" arity="2" since="OTP 21.0"/> + <fsummary>Extract a value from a map</fsummary> + <desc> + <p>Returns value <c><anno>Value</anno></c> associated with + <c><anno>Key</anno></c> if <c><anno>Map</anno></c> contains + <c><anno>Key</anno></c>.</p> + <p>The call fails with a <c>{badmap,Map}</c> exception if + <c><anno>Map</anno></c> is not a map, or with a <c>{badkey,Key}</c> + exception if no value is associated with <c><anno>Key</anno></c>.</p> + <p><em>Example:</em></p> + <code type="none"> +> Key = 1337, + Map = #{42 => value_two,1337 => "value one","a" => 1}, + map_get(Key,Map). +"value one"</code> + </desc> + </func> + + <func> + <name name="map_size" arity="1" since="OTP 17.0"/> <fsummary>Return the size of a map.</fsummary> <desc> <p>Returns an integer, which is the number of key-value pairs @@ -2722,7 +3033,7 @@ os_prompt%</pre> </func> <func> - <name name="match_spec_test" arity="3"/> + <name name="match_spec_test" arity="3" since="OTP 19.0"/> <fsummary>Test that a match specification works.</fsummary> <desc> <p>Tests a match specification used in calls to @@ -2760,7 +3071,7 @@ os_prompt%</pre> </func> <func> - <name name="max" arity="2"/> + <name name="max" arity="2" since=""/> <fsummary>Return the largest of two terms.</fsummary> <desc> <p>Returns the largest of <c><anno>Term1</anno></c> and @@ -2770,7 +3081,7 @@ os_prompt%</pre> </func> <func> - <name name="md5" arity="1"/> + <name name="md5" arity="1" since=""/> <fsummary>Compute an MD5 message digest.</fsummary> <desc> <p>Computes an MD5 message digest from <c><anno>Data</anno></c>, where @@ -2788,7 +3099,7 @@ os_prompt%</pre> </func> <func> - <name name="md5_final" arity="1"/> + <name name="md5_final" arity="1" since=""/> <fsummary>Finish the update of an MD5 context and return the computed MD5 message digest.</fsummary> <desc> @@ -2798,7 +3109,7 @@ os_prompt%</pre> </func> <func> - <name name="md5_init" arity="0"/> + <name name="md5_init" arity="0" since=""/> <fsummary>Create an MD5 context.</fsummary> <desc> <p>Creates an MD5 context, to be used in the following calls to @@ -2807,7 +3118,7 @@ os_prompt%</pre> </func> <func> - <name name="md5_update" arity="2"/> + <name name="md5_update" arity="2" since=""/> <fsummary>Update an MD5 context with data and return a new context. </fsummary> <desc> @@ -2818,7 +3129,7 @@ os_prompt%</pre> </func> <func> - <name name="memory" arity="0"/> + <name name="memory" arity="0" since=""/> <fsummary>Information about dynamically allocated memory.</fsummary> <type name="memory_type"/> <desc> @@ -2851,7 +3162,10 @@ os_prompt%</pre> <p>The total amount of memory currently allocated for the emulator that is not directly related to any Erlang process. Memory presented as <c>processes</c> is not - included in this memory.</p> + included in this memory. <seealso marker="tools:instrument"> + <c>instrument(3)</c></seealso> can be used to + get a more detailed breakdown of what memory is part + of this type.</p> </item> <tag><c>atom</c></tag> <item> @@ -2959,8 +3273,8 @@ RealSystem = system + MissedSystem</code> </func> <func> - <name name="memory" arity="1" clause_i="1"/> - <name name="memory" arity="1" clause_i="2"/> + <name name="memory" arity="1" clause_i="1" since=""/> + <name name="memory" arity="1" clause_i="2" since=""/> <fsummary>Information about dynamically allocated memory.</fsummary> <type name="memory_type"/> <desc> @@ -2999,7 +3313,7 @@ RealSystem = system + MissedSystem</code> </func> <func> - <name name="min" arity="2"/> + <name name="min" arity="2" since=""/> <fsummary>Return the smallest of two terms.</fsummary> <desc> <p>Returns the smallest of <c><anno>Term1</anno></c> and @@ -3009,7 +3323,7 @@ RealSystem = system + MissedSystem</code> </func> <func> - <name name="module_loaded" arity="1"/> + <name name="module_loaded" arity="1" since=""/> <fsummary>Check if a module is loaded.</fsummary> <desc> <p>Returns <c>true</c> if the module <c><anno>Module</anno></c> @@ -3024,9 +3338,9 @@ RealSystem = system + MissedSystem</code> </func> <func> - <name name="monitor" arity="2" clause_i="1"/> - <name name="monitor" arity="2" clause_i="2"/> - <name name="monitor" arity="2" clause_i="3"/> + <name name="monitor" arity="2" clause_i="1" since=""/> + <name name="monitor" arity="2" clause_i="2" since="?"/> + <name name="monitor" arity="2" clause_i="3" since="OTP 18.0"/> <fsummary>Start monitoring.</fsummary> <type name="registered_name"/> <type name="registered_process_identifier"/> @@ -3088,25 +3402,6 @@ RealSystem = system + MissedSystem</code> monitored process resides). </p></item> </taglist> - <p>If an attempt is made to monitor a process on an older node - (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> - <note> - <p>The format of the <c>'DOWN'</c> message changed in ERTS - 5.2 (Erlang/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 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 (ERTS 5.2 - or higher versions) always get <c>'DOWN'</c> messages on - the new format even if they are monitoring processes on old - 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> @@ -3114,7 +3409,19 @@ RealSystem = system + MissedSystem</code> 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> + located elsewhere.</p> + + <note><p>Before ERTS 10.0 (OTP 21.0), monitoring a process could fail with + <c>badarg</c> if the monitored process resided on a primitive node + (such as erl_interface or jinterface), where remote process monitoring + is not implemented.</p> + <p>Now, such a call to <c>monitor</c> will instead succeed and a + monitor is created. But the monitor will only supervise the + connection. That is, a <c>{'DOWN', _, process, _, noconnection}</c> is + the only message that may be received, as the primitive node have no + way of reporting the status of the monitored process.</p> + </note> + </item> <tag>Monitoring a <marker id="monitor_port"/><c>port</c></tag> @@ -3205,7 +3512,7 @@ RealSystem = system + MissedSystem</code> </func> <func> - <name name="monitor_node" arity="2"/> + <name name="monitor_node" arity="2" since=""/> <fsummary>Monitor the status of a node.</fsummary> <desc> <p>Monitor the status of the node <c><anno>Node</anno></c>. @@ -3229,7 +3536,7 @@ RealSystem = system + MissedSystem</code> </func> <func> - <name name="monitor_node" arity="3"/> + <name name="monitor_node" arity="3" since=""/> <fsummary>Monitor the status of a node.</fsummary> <desc> <p>Behaves as @@ -3255,7 +3562,7 @@ RealSystem = system + MissedSystem</code> </func> <func> - <name name="monotonic_time" arity="0"/> + <name name="monotonic_time" arity="0" since="OTP 18.0"/> <fsummary>Current Erlang monotonic time.</fsummary> <desc> <p>Returns the current @@ -3289,7 +3596,7 @@ RealSystem = system + MissedSystem</code> </func> <func> - <name name="monotonic_time" arity="1"/> + <name name="monotonic_time" arity="1" since="OTP 18.0"/> <fsummary>Current Erlang monotonic time.</fsummary> <desc> <p>Returns the current @@ -3307,7 +3614,7 @@ RealSystem = system + MissedSystem</code> </func> <func> - <name name="nif_error" arity="1"/> + <name name="nif_error" arity="1" since="OTP R14B"/> <fsummary>Stop execution with a specified reason.</fsummary> <desc> <p>Works exactly like @@ -3320,7 +3627,7 @@ RealSystem = system + MissedSystem</code> </func> <func> - <name name="nif_error" arity="2"/> + <name name="nif_error" arity="2" since="OTP R14B"/> <fsummary>Stop execution with a specified reason.</fsummary> <desc> <p>Works exactly like @@ -3333,7 +3640,7 @@ RealSystem = system + MissedSystem</code> </func> <func> - <name name="node" arity="0"/> + <name name="node" arity="0" since=""/> <fsummary>Name of the local node.</fsummary> <desc> <p>Returns the name of the local node. If the node is not alive, @@ -3343,7 +3650,7 @@ RealSystem = system + MissedSystem</code> </func> <func> - <name name="node" arity="1"/> + <name name="node" arity="1" since=""/> <fsummary>At which node a pid, port, or reference originates.</fsummary> <desc> <p>Returns the node where <c><anno>Arg</anno></c> originates. @@ -3356,7 +3663,7 @@ RealSystem = system + MissedSystem</code> </func> <func> - <name name="nodes" arity="0"/> + <name name="nodes" arity="0" since=""/> <fsummary>All visible nodes in the system.</fsummary> <desc> <p>Returns a list of all visible nodes in the system, except @@ -3365,7 +3672,7 @@ RealSystem = system + MissedSystem</code> </func> <func> - <name name="nodes" arity="1"/> + <name name="nodes" arity="1" since=""/> <fsummary>All nodes of a certain type in the system.</fsummary> <desc> <p>Returns a list of nodes according to the argument specified. @@ -3408,7 +3715,7 @@ RealSystem = system + MissedSystem</code> </func> <func> - <name name="now" arity="0"/> + <name name="now" arity="0" since=""/> <fsummary>Elapsed time since 00:00 GMT.</fsummary> <type name="timestamp"/> <desc> @@ -3437,7 +3744,7 @@ RealSystem = system + MissedSystem</code> </func> <func> - <name name="open_port" arity="2"/> + <name name="open_port" arity="2" since=""/> <fsummary>Open a port.</fsummary> <desc> <p>Returns a port identifier as the result of opening a @@ -3474,13 +3781,6 @@ RealSystem = system + MissedSystem</code> 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 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, <c>PATH</c> is searched (or an equivalent method is used to find programs, depending on the OS). This is done by invoking @@ -3579,6 +3879,12 @@ RealSystem = system + MissedSystem</code> </item> <tag><c>{env, <anno>Env</anno>}</c></tag> <item> + <p> + Types:<br/> + <c><anno>Name</anno> = </c><seealso marker="kernel:os#type-env_var_name"><c>os:env_var_name()</c></seealso><br/> + <c><anno>Val</anno> = </c><seealso marker="kernel:os#type-env_var_value"><c>os:env_var_value()</c></seealso><c> | false</c><br/> + <c>Env = [{<anno>Name</anno>, <anno>Val</anno>}]</c> + </p> <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 @@ -3593,7 +3899,13 @@ RealSystem = system + MissedSystem</code> exception is <c><anno>Val</anno></c> being the atom <c>false</c> (in analogy with <seealso marker="kernel:os#getenv/1"><c>os:getenv/1</c></seealso>, - which removes the environment variable.</p> + which removes the environment variable. + </p> + <p> + For information about encoding requirements, see documentation + of the types for <c><anno>Name</anno></c> and + <c><anno>Val</anno></c>. + </p> </item> <tag><c>{args, [ string() | binary() ]}</c></tag> <item> @@ -3773,7 +4085,7 @@ RealSystem = system + MissedSystem</code> </func> <func> - <name name="phash" arity="2"/> + <name name="phash" arity="2" since=""/> <fsummary>Portable hash function.</fsummary> <type_desc variable="Range">Range = 1..2^32, Hash = 1..Range</type_desc> <desc> @@ -3784,15 +4096,12 @@ RealSystem = system + MissedSystem</code> <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"/> + <name name="phash2" arity="1" since=""/> + <name name="phash2" arity="2" since=""/> <fsummary>Portable hash function.</fsummary> <type_desc variable="Range">1..2^32</type_desc> <type_desc variable="Hash">0..Range-1</type_desc> @@ -3816,20 +4125,16 @@ RealSystem = system + MissedSystem</code> </func> <func> - <name name="pid_to_list" arity="1"/> + <name name="pid_to_list" arity="1" since=""/> <fsummary>Text representation of a pid.</fsummary> <desc> <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 is not to be used - in application programs.</p> - </warning> </desc> </func> <func> - <name name="port_call" arity="3"/> + <name name="port_call" arity="3" since=""/> <fsummary>Perform a synchronous call to a port with term data.</fsummary> <desc> <p>Performs a synchronous call to a port. The meaning of @@ -3874,7 +4179,7 @@ RealSystem = system + MissedSystem</code> </func> <func> - <name name="port_close" arity="1"/> + <name name="port_close" arity="1" since=""/> <fsummary>Close an open port.</fsummary> <desc> <p>Closes an open port. Roughly the same as <c><anno>Port</anno> ! @@ -3914,7 +4219,7 @@ RealSystem = system + MissedSystem</code> </func> <func> - <name name="port_command" arity="2"/> + <name name="port_command" arity="2" since=""/> <fsummary>Send data to a port.</fsummary> <desc> <p>Sends data to a port. Same as @@ -3961,7 +4266,7 @@ RealSystem = system + MissedSystem</code> </func> <func> - <name name="port_command" arity="3"/> + <name name="port_command" arity="3" since=""/> <fsummary>Send data to a port.</fsummary> <desc> <p>Sends data to a port. <c>port_command(Port, Data, [])</c> @@ -4020,7 +4325,7 @@ RealSystem = system + MissedSystem</code> </func> <func> - <name name="port_connect" arity="2"/> + <name name="port_connect" arity="2" since=""/> <fsummary>Set the owner of a port.</fsummary> <desc> <p>Sets the port owner (the connected port) to <c><anno>Pid</anno></c>. @@ -4089,7 +4394,7 @@ RealSystem = system + MissedSystem</code> </func> <func> - <name name="port_control" arity="3"/> + <name name="port_control" arity="3" since=""/> <fsummary>Perform a synchronous control operation on a port.</fsummary> <desc> <p>Performs a synchronous control operation on a port. @@ -4126,7 +4431,7 @@ RealSystem = system + MissedSystem</code> </func> <func> - <name name="port_info" arity="1"/> + <name name="port_info" arity="1" since=""/> <fsummary>Information about a port.</fsummary> <desc> <p>Returns a list containing tuples with information about @@ -4157,7 +4462,7 @@ RealSystem = system + MissedSystem</code> </func> <func> - <name name="port_info" arity="2" clause_i="1"/> + <name name="port_info" arity="2" clause_i="1" since=""/> <fsummary>Information about the connected process of a port.</fsummary> <desc> <p><c><anno>Pid</anno></c> is the process identifier of the process @@ -4173,7 +4478,7 @@ RealSystem = system + MissedSystem</code> </func> <func> - <name name="port_info" arity="2" clause_i="2"/> + <name name="port_info" arity="2" clause_i="2" since=""/> <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 @@ -4189,7 +4494,7 @@ RealSystem = system + MissedSystem</code> </func> <func> - <name name="port_info" arity="2" clause_i="3"/> + <name name="port_info" arity="2" clause_i="3" since=""/> <fsummary>Information about the input of a port.</fsummary> <desc> <p><c><anno>Bytes</anno></c> is the total number of bytes @@ -4205,7 +4510,7 @@ RealSystem = system + MissedSystem</code> </func> <func> - <name name="port_info" arity="2" clause_i="4"/> + <name name="port_info" arity="2" clause_i="4" since=""/> <fsummary>Information about the links of a port.</fsummary> <desc> <p><c><anno>Pids</anno></c> is a list of the process identifiers @@ -4221,12 +4526,11 @@ RealSystem = system + MissedSystem</code> </func> <func> - <name name="port_info" arity="2" clause_i="5"/> + <name name="port_info" arity="2" clause_i="5" since="?"/> <fsummary>Information about the locking of a port.</fsummary> <desc> <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> @@ -4243,7 +4547,7 @@ RealSystem = system + MissedSystem</code> </func> <func> - <name name="port_info" arity="2" clause_i="6"/> + <name name="port_info" arity="2" clause_i="6" since="?"/> <fsummary>Information about the memory size of a port.</fsummary> <desc> <p><c><anno>Bytes</anno></c> is the total number of @@ -4261,7 +4565,7 @@ RealSystem = system + MissedSystem</code> </func> <func> - <name name="port_info" arity="2" clause_i="7"/> + <name name="port_info" arity="2" clause_i="7" since="?"/> <fsummary>Information about the monitors of a port.</fsummary> <desc> <p><c><anno>Monitors</anno></c> represent processes monitored by @@ -4277,7 +4581,7 @@ RealSystem = system + MissedSystem</code> </func> <func> - <name name="port_info" arity="2" clause_i="8"/> + <name name="port_info" arity="2" clause_i="8" since="?"/> <fsummary>Which processes are monitoring this port.</fsummary> <desc> <p>Returns list of pids that are monitoring given port at the @@ -4293,7 +4597,7 @@ RealSystem = system + MissedSystem</code> </func> <func> - <name name="port_info" arity="2" clause_i="9"/> + <name name="port_info" arity="2" clause_i="9" since=""/> <fsummary>Information about the name of a port.</fsummary> <desc> <p><c><anno>Name</anno></c> is the command name set by @@ -4309,7 +4613,7 @@ RealSystem = system + MissedSystem</code> </func> <func> - <name name="port_info" arity="2" clause_i="10"/> + <name name="port_info" arity="2" clause_i="10" since="?"/> <fsummary>Information about the OS pid of a port.</fsummary> <desc> <p><c><anno>OsPid</anno></c> is the process identifier (or equivalent) @@ -4328,7 +4632,7 @@ RealSystem = system + MissedSystem</code> </func> <func> - <name name="port_info" arity="2" clause_i="11"/> + <name name="port_info" arity="2" clause_i="11" since=""/> <fsummary>Information about the output of a port.</fsummary> <desc> <p><c><anno>Bytes</anno></c> is the total number of bytes written @@ -4347,7 +4651,7 @@ RealSystem = system + MissedSystem</code> </func> <func> - <name name="port_info" arity="2" clause_i="12"/> + <name name="port_info" arity="2" clause_i="12" since="?"/> <fsummary>Information about the parallelism hint of a port.</fsummary> <desc> <p><c><anno>Boolean</anno></c> corresponds to the port parallelism @@ -4358,7 +4662,7 @@ RealSystem = system + MissedSystem</code> </func> <func> - <name name="port_info" arity="2" clause_i="13"/> + <name name="port_info" arity="2" clause_i="13" since="?"/> <fsummary>Information about the queue size of a port.</fsummary> <desc> <p><c><anno>Bytes</anno></c> is the total number @@ -4375,7 +4679,7 @@ RealSystem = system + MissedSystem</code> </func> <func> - <name name="port_info" arity="2" clause_i="14"/> + <name name="port_info" arity="2" clause_i="14" since=""/> <fsummary>Information about the registered name of a port.</fsummary> <desc> <p><c><anno>RegisteredName</anno></c> is the registered name of @@ -4392,20 +4696,16 @@ RealSystem = system + MissedSystem</code> </func> <func> - <name name="port_to_list" arity="1"/> + <name name="port_to_list" arity="1" since=""/> <fsummary>Text representation of a port identifier.</fsummary> <desc> <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. It is not to be used - in application programs.</p> - </warning> </desc> </func> <func> - <name name="ports" arity="0"/> + <name name="ports" arity="0" since=""/> <fsummary>List all existing ports.</fsummary> <desc> <p>Returns a list of port identifiers corresponding to all the @@ -4415,7 +4715,7 @@ RealSystem = system + MissedSystem</code> </func> <func> - <name name="pre_loaded" arity="0"/> + <name name="pre_loaded" arity="0" since=""/> <fsummary>List all preloaded modules.</fsummary> <desc> <p>Returns a list of Erlang modules that are preloaded in @@ -4426,7 +4726,7 @@ RealSystem = system + MissedSystem</code> </func> <func> - <name name="process_display" arity="2"/> + <name name="process_display" arity="2" since=""/> <fsummary>Write information about a local process on standard error. </fsummary> <desc> @@ -4440,7 +4740,7 @@ RealSystem = system + MissedSystem</code> </func> <func> - <name name="process_flag" arity="2" clause_i="1"/> + <name name="process_flag" arity="2" clause_i="1" since=""/> <fsummary>Set process flag trap_exit for the calling process.</fsummary> <desc> <p>When <c>trap_exit</c> is set to <c>true</c>, exit signals @@ -4457,7 +4757,7 @@ RealSystem = system + MissedSystem</code> </func> <func> - <name name="process_flag" arity="2" clause_i="2"/> + <name name="process_flag" arity="2" clause_i="2" since=""/> <fsummary>Set process flag error_handler for the calling process. </fsummary> <desc> @@ -4471,18 +4771,18 @@ RealSystem = system + MissedSystem</code> </func> <func> - <name name="process_flag" arity="2" clause_i="3"/> + <name name="process_flag" arity="2" clause_i="3" + anchor="process_flag_min_heap_size" since=""/> <fsummary>Set process flag min_heap_size for the calling process. </fsummary> <desc> - <marker id="process_flag_min_heap_size"/> <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"/> + <name name="process_flag" arity="2" clause_i="4" since="?"/> <fsummary>Set process flag min_bin_vheap_size for the calling process. </fsummary> <desc> @@ -4493,12 +4793,12 @@ RealSystem = system + MissedSystem</code> </func> <func> - <name name="process_flag" arity="2" clause_i="5"/> + <name name="process_flag" arity="2" clause_i="5" + anchor="process_flag_max_heap_size" since="?"/> <fsummary>Set process flag max_heap_size for the calling process. </fsummary> <type name="max_heap_size"/> <desc> - <marker id="process_flag_max_heap_size"/> <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. @@ -4541,11 +4841,11 @@ RealSystem = system + MissedSystem</code> </item> <tag><c>error_logger</c></tag> <item> - <p>When set to <c>true</c>, the runtime system sends a - message to the current <seealso marker="kernel:error_logger"> - <c>error_logger</c></seealso> + <p>When set to <c>true</c>, the runtime system logs an + error event via <seealso marker="kernel:logger"> + <c>logger</c></seealso>, containing details about the process when the maximum - heap size is reached. One <c>error_logger</c> report is sent + heap size is reached. One log event is sent each time the limit is reached.</p> <p>If <c>error_logger</c> is not defined in the map, the system default is used. The default system default is <c>true</c>. @@ -4559,7 +4859,7 @@ RealSystem = system + MissedSystem</code> 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 + the log events to see what the normal peak sizes of the processes in the system is and then tune the value accordingly. </p> @@ -4567,12 +4867,12 @@ RealSystem = system + MissedSystem</code> </func> <func> - <name name="process_flag" arity="2" clause_i="6"/> + <name name="process_flag" arity="2" clause_i="6" + anchor="process_flag_message_queue_data" since="?"/> <fsummary>Set process flag message_queue_data for the calling process. </fsummary> <type name="message_queue_data"/> <desc> - <marker id="process_flag_message_queue_data"/> <p>This flag determines how messages in the message queue are stored, as follows:</p> <taglist> @@ -4594,10 +4894,10 @@ RealSystem = system + MissedSystem</code> <p>The default <c>message_queue_data</c> process flag is determined by command-line argument <seealso marker="erl#+hmqd"> <c>+hmqd</c></seealso> in <c>erl(1)</c>.</p> - <p>If the process potentially can get many messages, + <p>If the process potentially can get many messages in its queue, you are advised to set the flag to <c>off_heap</c>. This because a garbage collection with many messages placed on - the heap can become extremly expensive and the process can + the heap can become extremely expensive and the process can consume large amounts of memory. Performance of the actual message passing is however generally better when not using flag <c>off_heap</c>.</p> @@ -4609,11 +4909,12 @@ RealSystem = system + MissedSystem</code> </func> <func> - <name name="process_flag" arity="2" clause_i="7"/> + <name name="process_flag" arity="2" clause_i="7" + anchor="process_flag_priority" since=""/> <fsummary>Set process flag priority for the calling process.</fsummary> <type name="priority_level"/> <desc> - <p><marker id="process_flag_priority"></marker> + <p> Sets the process priority. <c><anno>Level</anno></c> is an atom. Four priority levels exist: <c>low</c>, <c>normal</c>, <c>high</c>, and <c>max</c>. Default @@ -4634,8 +4935,8 @@ RealSystem = system + MissedSystem</code> 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 processes - are running on priority <c>high</c>. On the runtime - system with SMP support, more processes can be running + are running on priority <c>high</c>. When using multiple + schedulers, 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> @@ -4650,10 +4951,8 @@ RealSystem = system + MissedSystem</code> 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 likely to be - changed in a future release to use available - processor cores better.</p> + to remain exactly as it is today. Scheduling 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 @@ -4683,7 +4982,7 @@ RealSystem = system + MissedSystem</code> </func> <func> - <name name="process_flag" arity="2" clause_i="8"/> + <name name="process_flag" arity="2" clause_i="8" since=""/> <fsummary>Set process flag save_calls for the calling process.</fsummary> <desc> <p><c><anno>N</anno></c> must be an integer in the interval 0..10000. @@ -4714,7 +5013,7 @@ RealSystem = system + MissedSystem</code> </func> <func> - <name name="process_flag" arity="2" clause_i="9"/> + <name name="process_flag" arity="2" clause_i="9" since=""/> <fsummary>Set process flag sensitive for the calling process.</fsummary> <desc> <p>Sets or clears flag <c>sensitive</c> for the current process. @@ -4748,7 +5047,7 @@ RealSystem = system + MissedSystem</code> </func> <func> - <name name="process_flag" arity="3"/> + <name name="process_flag" arity="3" since="?"/> <fsummary>Set process flags for a process.</fsummary> <desc> <p>Sets certain flags for the process <c><anno>Pid</anno></c>, @@ -4763,7 +5062,7 @@ RealSystem = system + MissedSystem</code> </func> <func> - <name name="process_info" arity="1"/> + <name name="process_info" arity="1" since=""/> <fsummary>Information about a process.</fsummary> <type name="process_info_result_item"/> <type name="priority_level"/> @@ -4785,7 +5084,6 @@ RealSystem = system + MissedSystem</code> <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> @@ -4815,8 +5113,8 @@ RealSystem = system + MissedSystem</code> </func> <func> - <name name="process_info" arity="2" clause_i="1"/> - <name name="process_info" arity="2" clause_i="2"/> + <name name="process_info" arity="2" clause_i="1" since=""/> + <name name="process_info" arity="2" clause_i="2" since=""/> <fsummary>Information about a process.</fsummary> <type name="process_info_item"/> <type name="process_info_result_item"/> @@ -4867,11 +5165,15 @@ RealSystem = system + MissedSystem</code> <tag><c>{binary, <anno>BinInfo</anno>}</c></tag> <item> <p><c><anno>BinInfo</anno></c> is a list containing miscellaneous - information about binaries currently referred to by this - process. This <c><anno>InfoTuple</anno></c> can be changed or + information about binaries on the heap of this + process. + This <c><anno>InfoTuple</anno></c> can be changed or removed without prior notice. In the current implementation <c><anno>BinInfo</anno></c> is a list of tuples. The tuples contain; <c>BinaryId</c>, <c>BinarySize</c>, <c>BinaryRefcCount</c>.</p> + <p>The message queue is on the heap depending on the + process flag <seealso marker="#process_flag_message_queue_data"> + <c>message_queue_data</c></seealso>.</p> </item> <tag><c>{catchlevel, <anno>CatchLevel</anno>}</c></tag> <item> @@ -4995,10 +5297,10 @@ RealSystem = system + MissedSystem</code> <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> + <tag><c>{monitored_by, <anno>MonitoredBy</anno>}</c></tag> <item> - <p>A list of process identifiers monitoring the process (with - <c>monitor/2</c>).</p> + <p>A list of identifiers for all the processes, ports and NIF + resources, that are monitoring the process.</p> </item> <tag><c>{monitors, <anno>Monitors</anno>}</c></tag> <item> @@ -5145,7 +5447,7 @@ RealSystem = system + MissedSystem</code> </func> <func> - <name name="processes" arity="0"/> + <name name="processes" arity="0" since=""/> <fsummary>All processes.</fsummary> <desc> <p>Returns a list of process identifiers corresponding to @@ -5162,7 +5464,7 @@ RealSystem = system + MissedSystem</code> </func> <func> - <name name="purge_module" arity="1"/> + <name name="purge_module" arity="1" since=""/> <fsummary>Remove old code for a module.</fsummary> <desc> <p>Removes old code for <c><anno>Module</anno></c>. @@ -5187,7 +5489,7 @@ RealSystem = system + MissedSystem</code> </func> <func> - <name name="put" arity="2"/> + <name name="put" arity="2" since=""/> <fsummary>Add a new value to the process dictionary.</fsummary> <desc> <p>Adds a new <c><anno>Key</anno></c> to the process dictionary, @@ -5209,7 +5511,7 @@ RealSystem = system + MissedSystem</code> </func> <func> - <name name="raise" arity="3"/> + <name name="raise" arity="3" since=""/> <fsummary>Stop execution with an exception of specified class, reason, and call stack backtrace.</fsummary> <type name="raise_stacktrace"/> @@ -5248,7 +5550,7 @@ RealSystem = system + MissedSystem</code> </func> <func> - <name name="read_timer" arity="1"/> + <name name="read_timer" arity="1" since=""/> <fsummary>Read the state of a timer.</fsummary> <desc> <p>Reads the state of a timer. The same as calling @@ -5258,7 +5560,7 @@ RealSystem = system + MissedSystem</code> </func> <func> - <name name="read_timer" arity="2"/> + <name name="read_timer" arity="2" since="OTP 18.0"/> <fsummary>Read the state of a timer.</fsummary> <desc> <p>Reads the state of a timer that has been created by either @@ -5314,7 +5616,7 @@ RealSystem = system + MissedSystem</code> </func> <func> - <name name="ref_to_list" arity="1"/> + <name name="ref_to_list" arity="1" since=""/> <fsummary>Text representation of a reference.</fsummary> <desc> <p>Returns a string corresponding to the text @@ -5327,7 +5629,7 @@ RealSystem = system + MissedSystem</code> </func> <func> - <name name="register" arity="2"/> + <name name="register" arity="2" since=""/> <fsummary>Register a name for a pid (or port).</fsummary> <desc> <p>Associates the name <c><anno>RegName</anno></c> with a process @@ -5356,7 +5658,7 @@ true</pre> </func> <func> - <name name="registered" arity="0"/> + <name name="registered" arity="0" since=""/> <fsummary>All registered names.</fsummary> <desc> <p>Returns a list of names that have been registered using @@ -5369,7 +5671,7 @@ true</pre> </func> <func> - <name name="resume_process" arity="1"/> + <name name="resume_process" arity="1" since=""/> <fsummary>Resume a suspended process.</fsummary> <desc> <p>Decreases the suspend count on the process identified by @@ -5410,7 +5712,7 @@ true</pre> </func> <func> - <name name="round" arity="1"/> + <name name="round" arity="1" since=""/> <fsummary>Return an integer by rounding a number.</fsummary> <desc> <p>Returns an integer by rounding <c><anno>Number</anno></c>, @@ -5423,7 +5725,7 @@ true</pre> </func> <func> - <name name="self" arity="0"/> + <name name="self" arity="0" since=""/> <fsummary>Return pid of the calling process.</fsummary> <desc> <p>Returns the process identifier of the calling process, for @@ -5436,21 +5738,27 @@ true</pre> </func> <func> - <name name="send" arity="2"/> + <name name="send" arity="2" since=""/> <fsummary>Send 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> + is the same as using the <seealso marker="doc/reference_manual:expressions#send"> + send operator</seealso>: + <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> + for a registered name at another node.</p> + <p>The function fails with a <c>badarg</c> run-time error if + <c><anno>Dest</anno></c> is an atom name, but this name is not + registered. This is the only case when <c>send</c> fails for an + unreachable destination <c><anno>Dest</anno></c> (of correct type).</p> </desc> </func> <func> - <name name="send" arity="3"/> + <name name="send" arity="3" since=""/> <fsummary>Send a message conditionally.</fsummary> <type name="dst"/> <desc> @@ -5482,7 +5790,7 @@ true</pre> </func> <func> - <name name="send_after" arity="3"/> + <name name="send_after" arity="3" since=""/> <fsummary>Start a timer.</fsummary> <desc> <p>Starts a timer. The same as calling @@ -5493,7 +5801,7 @@ true</pre> </func> <func> - <name name="send_after" arity="4"/> + <name name="send_after" arity="4" since="OTP 18.0"/> <fsummary>Start a timer.</fsummary> <desc> <p>Starts a timer. When the timer expires, the message @@ -5506,7 +5814,7 @@ true</pre> </func> <func> - <name name="send_nosuspend" arity="2"/> + <name name="send_nosuspend" arity="2" since=""/> <fsummary>Try to send a message without ever blocking.</fsummary> <type name="dst"/> <desc> @@ -5556,7 +5864,7 @@ true</pre> </func> <func> - <name name="send_nosuspend" arity="3"/> + <name name="send_nosuspend" arity="3" since=""/> <fsummary>Try to send a message without ever blocking.</fsummary> <type name="dst"/> <desc> @@ -5589,7 +5897,7 @@ true</pre> </func> <func> - <name name="set_cookie" arity="2"/> + <name name="set_cookie" arity="2" since=""/> <fsummary>Set the magic cookie of a node.</fsummary> <desc> <p>Sets the magic cookie of <c><anno>Node</anno></c> to the atom @@ -5606,7 +5914,7 @@ true</pre> </func> <func> - <name name="setelement" arity="3"/> + <name name="setelement" arity="3" since=""/> <fsummary>Set the Nth element of a tuple.</fsummary> <type_desc variable="Index">1..tuple_size(<anno>Tuple1</anno></type_desc> <desc> @@ -5623,7 +5931,7 @@ true</pre> </func> <func> - <name name="size" arity="1"/> + <name name="size" arity="1" since=""/> <fsummary>Size of a tuple or binary.</fsummary> <desc> <p>Returns the number of elements in a tuple or the number of @@ -5646,7 +5954,7 @@ true</pre> </func> <func> - <name name="spawn" arity="1"/> + <name name="spawn" arity="1" since=""/> <fsummary>Create a new process with a fun as entry point.</fsummary> <desc> <p>Returns the process identifier of a new process started by the @@ -5657,7 +5965,7 @@ true</pre> </func> <func> - <name name="spawn" arity="2"/> + <name name="spawn" arity="2" since=""/> <fsummary>Create a new process with a fun as entry point on a specified node.</fsummary> <desc> @@ -5671,7 +5979,7 @@ true</pre> </func> <func> - <name name="spawn" arity="3"/> + <name name="spawn" arity="3" since=""/> <fsummary>Create a new process with a function as entry point.</fsummary> <desc> <p>Returns the process identifier of a new process started by @@ -5696,7 +6004,7 @@ true</pre> </func> <func> - <name name="spawn" arity="4"/> + <name name="spawn" arity="4" since=""/> <fsummary>Create a new process with a function as entry point on a specified node.</fsummary> <desc> @@ -5711,7 +6019,7 @@ true</pre> </func> <func> - <name name="spawn_link" arity="1"/> + <name name="spawn_link" arity="1" since=""/> <fsummary>Create and link to a new process with a fun as entry point. </fsummary> <desc> @@ -5725,7 +6033,7 @@ true</pre> </func> <func> - <name name="spawn_link" arity="2"/> + <name name="spawn_link" arity="2" since=""/> <fsummary>Create and link to a new process with a fun as entry point on a specified node.</fsummary> <desc> @@ -5742,7 +6050,7 @@ true</pre> </func> <func> - <name name="spawn_link" arity="3"/> + <name name="spawn_link" arity="3" since=""/> <fsummary>Create and link to a new process with a function as entry point. </fsummary> <desc> @@ -5756,7 +6064,7 @@ true</pre> </func> <func> - <name name="spawn_link" arity="4"/> + <name name="spawn_link" arity="4" since=""/> <fsummary>Create and link to a new process with a function as entry point on a specified node.</fsummary> <desc> @@ -5774,7 +6082,7 @@ true</pre> </func> <func> - <name name="spawn_monitor" arity="1"/> + <name name="spawn_monitor" arity="1" since=""/> <fsummary>Create and monitor a new process with a fun as entry point. </fsummary> <desc> @@ -5788,7 +6096,7 @@ true</pre> </func> <func> - <name name="spawn_monitor" arity="3"/> + <name name="spawn_monitor" arity="3" since=""/> <fsummary>Create and monitor a new process with a function as entry point. </fsummary> <desc> @@ -5802,7 +6110,7 @@ true</pre> </func> <func> - <name name="spawn_opt" arity="2"/> + <name name="spawn_opt" arity="2" since=""/> <fsummary>Create a new process with a fun as entry point.</fsummary> <type name="priority_level"/> <type name="max_heap_size"/> @@ -5820,7 +6128,7 @@ true</pre> </func> <func> - <name name="spawn_opt" arity="3"/> + <name name="spawn_opt" arity="3" since=""/> <fsummary>Create a new process with a fun as entry point on a specified node.</fsummary> <type name="priority_level"/> @@ -5838,7 +6146,7 @@ true</pre> </func> <func> - <name name="spawn_opt" arity="4"/> + <name name="spawn_opt" arity="4" since=""/> <fsummary>Create a new process with a function as entry point.</fsummary> <type name="priority_level"/> <type name="max_heap_size"/> @@ -5864,7 +6172,7 @@ true</pre> <p>Monitors the new process (like <seealso marker="#monitor/2"><c>monitor/2</c></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"> @@ -5974,7 +6282,7 @@ true</pre> </func> <func> - <name name="spawn_opt" arity="5"/> + <name name="spawn_opt" arity="5" since=""/> <fsummary>Create a new process with a function as entry point on a specified node.</fsummary> <type name="priority_level"/> @@ -5997,7 +6305,7 @@ true</pre> </func> <func> - <name name="split_binary" arity="2"/> + <name name="split_binary" arity="2" since=""/> <fsummary>Split a binary into two.</fsummary> <type_desc variable="Pos">0..byte_size(Bin)</type_desc> <desc> @@ -6021,7 +6329,7 @@ true</pre> </func> <func> - <name name="start_timer" arity="3"/> + <name name="start_timer" arity="3" since=""/> <fsummary>Start a timer.</fsummary> <desc> <p>Starts a timer. The same as calling @@ -6032,7 +6340,7 @@ true</pre> </func> <func> - <name name="start_timer" arity="4"/> + <name name="start_timer" arity="4" since="OTP 18.0"/> <fsummary>Start a timer.</fsummary> <desc> <p>Starts a timer. When the timer expires, the message @@ -6090,32 +6398,64 @@ true</pre> </func> <func> - <name name="statistics" arity="1" clause_i="1"/> + <name name="statistics" arity="1" clause_i="1" + anchor="statistics_active_tasks" since="?"/> + <fsummary>Information about active processes and ports.</fsummary> + <desc> + <p>Returns the same as + <seealso marker="#statistics_active_tasks_all"> + <c>statistics(active_tasks_all)</c></seealso> + with the exception that no information about the dirty + IO run queue and its associated schedulers is part of + the result. That is, only tasks that are expected to be + CPU bound are part of the result.</p> + </desc> + </func> + + <func> + <name name="statistics" arity="1" clause_i="2" + anchor="statistics_active_tasks_all" since="?"/> <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.</p> + associated schedulers. That is, the number of processes and + ports that are ready to run, or are currently running. + Values for normal run queues and their associated schedulers + are located first in the resulting list. The first element + corresponds to scheduler number 1 and so on. If support for + dirty schedulers exist, an element with the value for the + dirty CPU run queue and its associated dirty CPU schedulers + follow and then as last element the value for the the dirty + IO run queue and its associated dirty IO schedulers follow. + 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.</p> + <note><p>Each normal scheduler has one run queue that it + manages. If dirty schedulers schedulers are supported, all + dirty CPU schedulers share one run queue, and all dirty IO + schedulers share one run queue. That is, we have multiple + normal run queues, one dirty CPU run queue and one dirty + IO run queue. Work can <em>not</em> migrate between the + different types of run queues. Only work in normal run + queues can migrate to other normal run queues. This has + to be taken into account when evaluating the result.</p></note> <p>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 + <c>statistics(run_queue_lengths)</c></seealso>, + <seealso marker="#statistics_run_queue_lengths_all"> + <c>statistics(run_queue_lengths_all)</c></seealso>, <seealso marker="#statistics_total_run_queue_lengths"> - <c>statistics(total_run_queue_lengths)</c></seealso>.</p> + <c>statistics(total_run_queue_lengths)</c></seealso>, and + <seealso marker="#statistics_total_run_queue_lengths_all"> + <c>statistics(total_run_queue_lengths_all)</c></seealso>.</p> </desc> </func> <func> - <name name="statistics" arity="1" clause_i="2"/> + <name name="statistics" arity="1" clause_i="3" since=""/> <fsummary>Information about context switches.</fsummary> <desc> <p>Returns the total number of context switches since the @@ -6124,23 +6464,22 @@ true</pre> </func> <func> - <name name="statistics" arity="1" clause_i="3"/> + <name name="statistics" arity="1" clause_i="4" + anchor="statistics_exact_reductions" since=""/> <fsummary>Information about exact reductions.</fsummary> <desc> - <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> + statistics(reductions)</seealso>.</p> </note> </desc> </func> <func> - <name name="statistics" arity="1" clause_i="4"/> + <name name="statistics" arity="1" clause_i="5" since=""/> <fsummary>Information about garbage collection.</fsummary> <desc> <p>Returns information about garbage collection, for example:</p> @@ -6152,7 +6491,7 @@ true</pre> </func> <func> - <name name="statistics" arity="1" clause_i="5"/> + <name name="statistics" arity="1" clause_i="6" since=""/> <fsummary>Information about I/O.</fsummary> <desc> <p>Returns <c><anno>Input</anno></c>, @@ -6163,10 +6502,10 @@ true</pre> </func> <func> - <name name="statistics" arity="1" clause_i="6"/> + <name name="statistics" arity="1" clause_i="7" + anchor="statistics_microstate_accounting" since="?"/> <fsummary>Information about microstate accounting.</fsummary> <desc> - <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 some overhead exists when this @@ -6211,17 +6550,24 @@ lists:map( <p><c><anno>MSAcc_Thread_Type</anno></c>s:</p> <taglist> <tag><c>scheduler</c></tag> - <item>The main execution threads that do most of the work.</item> + <item>The main execution threads that do most of the work. See + <seealso marker="erts:erl#+S">erl +S</seealso> for more details.</item> <tag><c>dirty_cpu_scheduler</c></tag> - <item>The threads for long running cpu intensive work.</item> + <item>The threads for long running cpu intensive work. See + <seealso marker="erts:erl#+SDcpu">erl +SDcpu</seealso> for more details.</item> <tag><c>dirty_io_scheduler</c></tag> - <item>The threads for long running I/O work.</item> + <item>The threads for long running I/O work. See + <seealso marker="erts:erl#+SDio">erl +SDio</seealso> for more details.</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> + file drivers) do offload non-CPU intensive work. See + <seealso marker="erts:erl#+async_thread_pool_size">erl +A</seealso> for more details.</item> <tag><c>aux</c></tag> <item>Takes care of any work that is not specifically assigned to a scheduler.</item> + <tag><c>poll</c></tag> + <item>Does the IO polling for the emulator. See + <seealso marker="erts:erl#+IOt">erl +IOt</seealso> for more details.</item> </taglist> <p>The following <c><anno>MSAcc_Thread_State</anno></c>s are available. All states are exclusive, meaning that a thread cannot be in two @@ -6299,10 +6645,10 @@ lists:map( </func> <func> - <name name="statistics" arity="1" clause_i="7"/> + <name name="statistics" arity="1" clause_i="8" + anchor="statistics_reductions" since=""/> <fsummary>Information about reductions.</fsummary> <desc> - <marker id="statistics_reductions"></marker> <p>Returns information about reductions, for example:</p> <pre> > <input>statistics(reductions).</input> @@ -6318,12 +6664,14 @@ lists:map( </func> <func> - <name name="statistics" arity="1" clause_i="8"/> + <name name="statistics" arity="1" clause_i="9" + anchor="statistics_run_queue" since=""/> <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 + <desc> + <p>Returns the total length of all normal 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 + normal run-queues. Dirty run queues are not part of the + result. 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"> @@ -6333,29 +6681,65 @@ lists:map( </func> <func> - <name name="statistics" arity="1" clause_i="9"/> + <name name="statistics" arity="1" clause_i="10" + anchor="statistics_run_queue_lengths" since="?"/> + <fsummary>Information about the run-queue lengths.</fsummary> + <desc> + <p>Returns the same as + <seealso marker="#statistics_run_queue_lengths_all"> + <c>statistics(run_queue_lengths_all)</c></seealso> + with the exception that no information about the dirty + IO run queue is part of the result. That is, only + run queues with work that is expected to be CPU bound + is part of the result.</p> + </desc> + </func> + + <func> + <name name="statistics" arity="1" clause_i="11" + anchor="statistics_run_queue_lengths_all" since="?"/> <fsummary>Information about the run-queue lengths.</fsummary> - <desc><marker id="statistics_run_queue_lengths"></marker> + <desc> <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.</p> + of processes and ports ready to run for each run queue. + Values for normal run queues are located first in the + resulting list. The first element corresponds to the + normal run queue of scheduler number 1 and so on. If + support for dirty schedulers exist, values for the dirty + CPU run queue and the dirty IO run queue follow (in that + order) at the end. 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.</p> + <note><p>Each normal scheduler has one run queue that it + manages. If dirty schedulers schedulers are supported, all + dirty CPU schedulers share one run queue, and all dirty IO + schedulers share one run queue. That is, we have multiple + normal run queues, one dirty CPU run queue and one dirty + IO run queue. Work can <em>not</em> migrate between the + different types of run queues. Only work in normal run + queues can migrate to other normal run queues. This has + to be taken into account when evaluating the result.</p></note> <p>See also + <seealso marker="#statistics_run_queue_lengths"> + <c>statistics(run_queue_lengths)</c></seealso>, + <seealso marker="#statistics_total_run_queue_lengths_all"> + <c>statistics(total_run_queue_lengths_all)</c></seealso>, <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 + <c>statistics(active_tasks)</c></seealso>, + <seealso marker="#statistics_active_tasks_all"> + <c>statistics(active_tasks_all)</c></seealso>, and <seealso marker="#statistics_total_active_tasks"> - <c>statistics(total_active_tasks)</c></seealso>.</p> + <c>statistics(total_active_tasks)</c></seealso>, + <seealso marker="#statistics_total_active_tasks_all"> + <c>statistics(total_active_tasks_all)</c></seealso>.</p> </desc> </func> <func> - <name name="statistics" arity="1" clause_i="10"/> + <name name="statistics" arity="1" clause_i="12" since=""/> <fsummary>Information about runtime.</fsummary> <desc> <p>Returns information about runtime, in milliseconds.</p> @@ -6373,10 +6757,10 @@ lists:map( </func> <func> - <name name="statistics" arity="1" clause_i="11"/> + <name name="statistics" arity="1" clause_i="13" + anchor="statistics_scheduler_wall_time" since="?"/> <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 @@ -6386,12 +6770,17 @@ lists:map( <c><anno>TotalTime</anno></c> is the total time duration since <seealso marker="#system_flag_scheduler_wall_time"> <c>scheduler_wall_time</c></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> + activation for the specific scheduler. Note that + activation time can differ significantly between + schedulers. Currently dirty schedulers are activated + at system start while normal schedulers are activated + some time after the <c>scheduler_wall_time</c> + functionality is enabled. 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> @@ -6409,15 +6798,40 @@ lists:map( <c>scheduler_wall_time</c></seealso> is turned off.</p> <p>The list of scheduler information is unsorted and can appear in different order between calls.</p> + <p>As of ERTS version 9.0, also dirty CPU schedulers will + be included in the result. That is, all scheduler threads + that are expected to handle CPU bound work. If you also + want information about dirty I/O schedulers, use + <seealso marker="#statistics_scheduler_wall_time_all"> + <c>statistics(scheduler_wall_time_all)</c></seealso> + instead.</p> + + <p>Normal schedulers will have scheduler identifiers in + the range <c>1 =< <anno>SchedulerId</anno> =< + </c><seealso marker="#system_info_schedulers"> + <c>erlang:system_info(schedulers)</c></seealso>. + Dirty CPU schedulers will have scheduler identifiers in + the range <c>erlang:system_info(schedulers) < + <anno>SchedulerId</anno> =< erlang:system_info(schedulers) + + + </c><seealso marker="#system_info_dirty_cpu_schedulers"> + <c>erlang:system_info(dirty_cpu_schedulers)</c></seealso>. + </p> + <note><p>The different types of schedulers handle + specific types of jobs. Every job is assigned to a specific + scheduler type. Jobs can migrate between different schedulers + of the same type, but never between schedulers of different + types. This fact has to be taken under consideration when + evaluating the result returned.</p></note> <p>Using <c>scheduler_wall_time</c> to calculate - scheduler-utilization:</p> + 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 the user takes another snapshot and calculates - scheduler-utilization per scheduler, for example:</p> + scheduler utilization per scheduler, for example:</p> <pre> > <input>Ts1 = lists:sort(erlang:statistics(scheduler_wall_time)), ok.</input> ok @@ -6432,11 +6846,32 @@ ok {7,0.973237033077876}, {8,0.9741297293248656}]</pre> <p>Using the same snapshots to calculate a total - scheduler-utilization:</p> + 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> + {Ai + (A1 - A0), Ti + (T1 - T0)} end, {0, 0}, lists:zip(Ts0,Ts1)), + TotalSchedulerUtilization = A/T.</input> +0.9769136803764825</pre> + <p>Total scheduler utilization will equal <c>1.0</c> when + all schedulers have been active all the time between the + two measurements.</p> + <p>Another (probably more) useful value is to calculate + total scheduler utilization weighted against maximum amount + of available CPU time:</p> + <pre> +> <input>WeightedSchedulerUtilization = (TotalSchedulerUtilization + * (erlang:system_info(schedulers) + + erlang:system_info(dirty_cpu_schedulers))) + / erlang:system_info(logical_processors_available).</input> 0.9769136803764825</pre> + <p>This weighted scheduler utilization will reach <c>1.0</c> + when schedulers are active the same amount of time as + maximum available CPU time. If more schedulers exist + than available logical processors, this value may + be greater than <c>1.0</c>.</p> + <p>As of ERTS version 9.0, the Erlang runtime system + will as default have more schedulers than logical processors. + This due to the dirty schedulers.</p> <note> <p><c>scheduler_wall_time</c> is by default disabled. To enable it, use @@ -6446,47 +6881,79 @@ ok </func> <func> - <name name="statistics" arity="1" clause_i="12"/> + <name name="statistics" arity="1" clause_i="14" + anchor="statistics_scheduler_wall_time_all" since="?"/> + <fsummary>Information about each schedulers work time.</fsummary> + <desc> + <p>The same as + <seealso marker="#statistics_scheduler_wall_time"><c>statistics(scheduler_wall_time)</c></seealso>, + except that it also include information about all dirty I/O + schedulers.</p> + <p>Dirty IO schedulers will have scheduler identifiers in + the range + <seealso marker="#system_info_schedulers"> + <c>erlang:system_info(schedulers)</c></seealso><c> + + + </c><seealso marker="#system_info_dirty_cpu_schedulers"> + <c>erlang:system_info(dirty_cpu_schedulers)</c></seealso><c> < + <anno>SchedulerId</anno> =< erlang:system_info(schedulers) + + erlang:system_info(dirty_cpu_schedulers) + + + </c><seealso marker="#system_info_dirty_io_schedulers"> + <c>erlang:system_info(dirty_io_schedulers)</c></seealso>.</p> + <note><p>Note that work executing on dirty I/O schedulers + are expected to mainly wait for I/O. That is, when you + get high scheduler utilization on dirty I/O schedulers, + CPU utilization is <em>not</em> expected to be high due to + this work.</p></note> + </desc> + </func> + <func> + <name name="statistics" arity="1" clause_i="15" + anchor="statistics_total_active_tasks" since="?"/> <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.</p> - <p>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> + <p>The same as calling + <c>lists:sum(</c><seealso marker="#statistics_active_tasks"><c>statistics(active_tasks)</c></seealso><c>)</c>, + but more efficient.</p> + </desc> + </func> + + <func> + <name name="statistics" arity="1" clause_i="16" + anchor="statistics_total_active_tasks_all" since="?"/> + <fsummary>Information about active processes and ports.</fsummary> + <desc> + <p>The same as calling + <c>lists:sum(</c><seealso marker="#statistics_active_tasks_all"><c>statistics(active_tasks_all)</c></seealso><c>)</c>, + but more efficient.</p> </desc> </func> <func> - <name name="statistics" arity="1" clause_i="13"/> + <name name="statistics" arity="1" clause_i="17" + anchor="statistics_total_run_queue_lengths" since="?"/> <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>.</p> - <p>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> + <p>The same as calling + <c>lists:sum(</c><seealso marker="#statistics_run_queue_lengths"><c>statistics(run_queue_lengths)</c></seealso><c>)</c>, + but more efficient.</p> </desc> </func> <func> - <name name="statistics" arity="1" clause_i="14"/> + <name name="statistics" arity="1" clause_i="18" + anchor="statistics_total_run_queue_lengths_all" since="?"/> + <fsummary>Information about the run-queue lengths.</fsummary> + <desc> + <p>The same as calling + <c>lists:sum(</c><seealso marker="#statistics_run_queue_lengths_all"><c>statistics(run_queue_lengths_all)</c></seealso><c>)</c>, + but more efficient.</p> + </desc> + </func> + + <func> + <name name="statistics" arity="1" clause_i="19" since=""/> <fsummary>Information about wall clock.</fsummary> <desc> <p>Returns information about wall clock. <c>wall_clock</c> can @@ -6497,7 +6964,7 @@ ok </func> <func> - <name name="suspend_process" arity="1"/> + <name name="suspend_process" arity="1" since=""/> <fsummary>Suspend a process.</fsummary> <desc> <p>Suspends the process identified by @@ -6512,7 +6979,7 @@ ok </func> <func> - <name name="suspend_process" arity="2"/> + <name name="suspend_process" arity="2" since=""/> <fsummary>Suspend a process.</fsummary> <desc> <p>Increases the suspend count on the process identified by @@ -6547,10 +7014,47 @@ ok 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> + is resumed). If no <c>asynchronous</c> options has been passed, the caller of <c>erlang:suspend_process/2</c> is blocked until <c><anno>Suspendee</anno></c> has suspended.</p> </item> + <tag><c>{asynchronous, ReplyTag}</c></tag> + <item> + <p>A suspend request is sent to the process identified by + <c><anno>Suspendee</anno></c>. When the suspend request + has been processed, a reply message is sent to the caller + of this function. The reply is on the form <c>{ReplyTag, + State}</c> where <c>State</c> is either:</p> + <taglist> + <tag><c>exited</c></tag> + <item> + <p> + <c><anno>Suspendee</anno></c> has exited. + </p> + </item> + <tag><c>suspended</c></tag> + <item> + <p> + <c><anno>Suspendee</anno></c> is now suspended. + </p> + </item> + <tag><c>not_suspended</c></tag> + <item> + <p> + <c><anno>Suspendee</anno></c> is not suspended. + This can only happen when the process that + issued this request, have called + <c>resume_process(<anno>Suspendee</anno>)</c> + before getting the reply. + </p> + </item> + </taglist> + <p> + Appart from the reply message, the <c>{asynchronous, + ReplyTag}</c> option behaves exactly the same as the + <c>asynchronous</c> option without reply tag. + </p> + </item> <tag><c>unless_suspending</c></tag> <item> <p>The process identified by <c><anno>Suspendee</anno></c> is @@ -6574,6 +7078,13 @@ ok <warning> <p>This BIF is intended for debugging only.</p> </warning> + <warning> + <p>You can easily create deadlocks if processes suspends + each other (directly or in circles). In ERTS versions prior + to ERTS version 10.0, the runtime system prevented such + deadlocks, but this prevention has now been removed due + to performance reasons.</p> + </warning> <p>Failures:</p> <taglist> <tag><c>badarg</c></tag> @@ -6614,7 +7125,7 @@ ok </func> <func> - <name name="system_flag" arity="2" clause_i="1"/> + <name name="system_flag" arity="2" clause_i="1" since=""/> <fsummary>Set system flag <c>backtrace_depth</c>.</fsummary> <desc> <p>Sets the maximum depth of call stack back-traces in the @@ -6626,7 +7137,8 @@ ok </func> <func> - <name name="system_flag" arity="2" clause_i="2"/> + <name name="system_flag" arity="2" clause_i="2" + anchor="system_flag_cpu_topology" since=""/> <fsummary>Set system flag <c>cpu_topology</c>.</fsummary> <type name="cpu_topology"/> <type name="level_entry"/> @@ -6635,7 +7147,7 @@ ok <type name="info_list"/> <desc> <warning> - <p><marker id="system_flag_cpu_topology"></marker> + <p> <em>This argument is deprecated.</em> Instead of using this argument, use command-line argument <seealso marker="erts:erl#+sct"><c>+sct</c></seealso> in @@ -6673,10 +7185,11 @@ ok </func> <func> - <name name="system_flag" arity="2" clause_i="3"/> + <name name="system_flag" arity="2" clause_i="3" + anchor="system_flag_dirty_cpu_schedulers_online" since="?"/> <fsummary>Set system_flag_dirty_cpu_schedulers_online.</fsummary> <desc> - <p><marker id="system_flag_dirty_cpu_schedulers_online"></marker> + <p> Sets the number of dirty CPU schedulers online. Range is <c><![CDATA[1 <= DirtyCPUSchedulersOnline <= N]]></c>, where <c>N</c> is the smallest of the return values of @@ -6692,11 +7205,6 @@ ok 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"> <c>erlang:system_info(dirty_cpu_schedulers)</c></seealso> and @@ -6706,7 +7214,24 @@ ok </func> <func> - <name name="system_flag" arity="2" clause_i="4"/> + <name name="system_flag" arity="2" clause_i="4" since="?"/> + <fsummary>Set system flag for erts_alloc.</fsummary> + <desc> + <p>Sets system flags for + <seealso marker="erts:erts_alloc"><c>erts_alloc(3)</c></seealso>. + <c><anno>Alloc</anno></c> is the allocator to affect, for example + <c>binary_alloc</c>. <c><anno>F</anno></c> is the flag to change and + <c><anno>V</anno></c> is the new value.</p> + <p>Only a subset of all <c>erts_alloc</c> flags can be changed + at run time. This subset is currently only the flag + <seealso marker="erts:erts_alloc#M_sbct"><c>sbct</c></seealso>.</p> + <p>Returns <c>ok</c> if the flag was set or <c>notsup</c> if not + supported by <c>erts_alloc</c>.</p> + </desc> + </func> + + <func> + <name name="system_flag" arity="2" clause_i="5" since=""/> <fsummary>Set system flag fullsweep_after.</fsummary> <desc> <p>Sets system flag <c>fullsweep_after</c>. @@ -6725,10 +7250,11 @@ ok </func> <func> - <name name="system_flag" arity="2" clause_i="5"/> + <name name="system_flag" arity="2" clause_i="6" + anchor="system_flag_microstate_accounting" since="?"/> <fsummary>Set system flag microstate_accounting.</fsummary> <desc> - <p><marker id="system_flag_microstate_accounting"></marker> + <p> Turns on/off microstate accounting measurements. When passing reset, all counters are reset to 0.</p> <p>For more information see @@ -6738,7 +7264,7 @@ ok </func> <func> - <name name="system_flag" arity="2" clause_i="6"/> + <name name="system_flag" arity="2" clause_i="7" since=""/> <fsummary>Set system flag min_heap_size.</fsummary> <desc> <p>Sets the default minimum heap size for processes. The size @@ -6753,7 +7279,7 @@ ok </func> <func> - <name name="system_flag" arity="2" clause_i="7"/> + <name name="system_flag" arity="2" clause_i="8" since="?"/> <fsummary>Set system flag min_bin_vheap_size.</fsummary> <desc> <p>Sets the default minimum binary virtual heap size for @@ -6770,28 +7296,29 @@ ok </func> <func> - <name name="system_flag" arity="2" clause_i="8"/> + <name name="system_flag" arity="2" clause_i="9" + anchor="system_flag_max_heap_size" since="?"/> <fsummary>Set system flag max_heap_size.</fsummary> <type name="max_heap_size"/> <desc> - <marker id="system_flag_max_heap_size"></marker> <p> Sets the default maximum heap size settings for processes. The size is specified 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"><c>spawn_opt/2,3,4</c></seealso> or - <seealso marker="#process_flag_message_queue_data"> + <seealso marker="#process_flag_max_heap_size"> <c>process_flag/2</c></seealso>.</p> <p>Returns the old value of the flag.</p> </desc> </func> <func> - <name name="system_flag" arity="2" clause_i="9"/> + <name name="system_flag" arity="2" clause_i="10" + anchor="system_flag_multi_scheduling" since=""/> <fsummary>Set system flag multi_scheduling.</fsummary> <desc> - <p><marker id="system_flag_multi_scheduling"></marker> + <p> If multi-scheduling is enabled, more than one scheduler thread is used by the emulator. Multi-scheduling can be blocked in two different ways. Either all schedulers but @@ -6843,12 +7370,13 @@ ok </func> <func> - <name name="system_flag" arity="2" clause_i="10"/> + <name name="system_flag" arity="2" clause_i="11" + anchor="system_flag_scheduler_bind_type" since=""/> <fsummary>Set system flag scheduler_bind_type.</fsummary> <type name="scheduler_bind_type"/> <desc> <warning> - <p><marker id="system_flag_scheduler_bind_type"></marker> + <p> <em>This argument is deprecated.</em> Instead of using this argument, use command-line argument <seealso marker="erts:erl#+sbt"><c>+sbt</c></seealso> in @@ -6863,7 +7391,7 @@ ok <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 + an error event is logged. To verify that the schedulers have bound as requested, call <seealso marker="#system_info_scheduler_bindings"> <c>erlang:system_info(scheduler_bindings)</c></seealso>.</p> @@ -6969,10 +7497,11 @@ ok </func> <func> - <name name="system_flag" arity="2" clause_i="11"/> + <name name="system_flag" arity="2" clause_i="12" + anchor="system_flag_scheduler_wall_time" since="?"/> <fsummary>Set system flag scheduler_wall_time.</fsummary> <desc> - <p><marker id="system_flag_scheduler_wall_time"></marker> + <p> Turns on or off scheduler wall time measurements.</p> <p>For more information, see <seealso marker="#statistics_scheduler_wall_time"> @@ -6981,10 +7510,11 @@ ok </func> <func> - <name name="system_flag" arity="2" clause_i="12"/> + <name name="system_flag" arity="2" clause_i="13" + anchor="system_flag_schedulers_online" since=""/> <fsummary>Set system flag schedulers_online.</fsummary> <desc> - <p><marker id="system_flag_schedulers_online"></marker> + <p> Sets the number of schedulers online. Range is <c><![CDATA[1 <= SchedulersOnline <= erlang:system_info(schedulers)]]></c>.</p> @@ -7009,7 +7539,7 @@ ok </func> <func> - <name name="system_flag" arity="2" clause_i="13"/> + <name name="system_flag" arity="2" clause_i="14" since=""/> <fsummary>Set system flag trace_control_word.</fsummary> <desc> <p>Sets the value of the node trace control word to @@ -7023,10 +7553,11 @@ ok </func> <func> - <name name="system_flag" arity="2" clause_i="14"/> + <name name="system_flag" arity="2" clause_i="15" + anchor="system_flag_time_offset" since="?"/> <fsummary>Finalize the time offset.</fsummary> <desc> - <p><marker id="system_flag_time_offset"></marker> + <p> 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 @@ -7052,11 +7583,145 @@ ok </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"/> + <name name="system_info" arity="1" clause_i="76" since=""/> + <fsummary>System info overview.</fsummary> + <desc> + <p>Returns information about the current system. + The documentation of this function is broken into the following + sections in order to make it easier to navigate.</p> + <taglist> + <tag><seealso marker="#system_info_allocator"> + <c>Memory Allocation</c></seealso></tag> + <item> + <p> + <seealso marker="#system_info_allocated_areas"><c>allocated_areas</c></seealso>, + <seealso marker="#system_info_allocator"><c>allocator</c></seealso>, + <seealso marker="#system_info_alloc_util_allocators"><c>alloc_util_allocators</c></seealso>, + <seealso marker="#system_info_allocator_sizes"><c>allocator_sizes</c></seealso>, + <seealso marker="#system_info_elib_malloc"><c>elib_malloc</c></seealso> + </p> + </item> + <tag><seealso marker="#system_info_cpu_topology"> + <c>CPU Topology</c></seealso></tag> + <item> + <p> + <seealso marker="#system_info_cpu_topology"><c>cpu_topology</c></seealso>, + <seealso marker="#system_info_logical_processors"><c>logical_processors</c></seealso>, + <seealso marker="#system_info_update_cpu_info"><c>update_cpu_info</c></seealso> + </p> + </item> + <tag><seealso marker="#system_info_process"> + <c>Process Information</c></seealso></tag> + <item> + <p> + <seealso marker="#system_info_fullsweep_after"><c>fullsweep_after</c></seealso>, + <seealso marker="#system_info_garbage_collection"><c>garbage_collection</c></seealso>, + <seealso marker="#system_info_heap_sizes"><c>heap_sizes</c></seealso>, + <seealso marker="#system_info_heap_type"><c>heap_type</c></seealso>, + <seealso marker="#system_info_max_heap_size"><c>max_heap_size</c></seealso>, + <seealso marker="#system_info_message_queue_data"><c>message_queue_data</c></seealso>, + <seealso marker="#system_info_min_heap_size"><c>min_heap_size</c></seealso>, + <seealso marker="#system_info_min_bin_vheap_size"><c>min_bin_vheap_size</c></seealso>, + <seealso marker="#system_info_procs"><c>procs</c></seealso> + </p> + </item> + <tag><seealso marker="#system_info_limits"> + <c>System Limits</c></seealso></tag> + <item> + <p> + <seealso marker="#system_info_atom_count"><c>atom_count</c></seealso>, + <seealso marker="#system_info_atom_limit"><c>atom_limit</c></seealso>, + <seealso marker="#system_info_ets_count"><c>ets_count</c></seealso>, + <seealso marker="#system_info_ets_limit"><c>ets_limit</c></seealso>, + <seealso marker="#system_info_port_count"><c>port_count</c></seealso>, + <seealso marker="#system_info_port_limit"><c>port_limit</c></seealso>, + <seealso marker="#system_info_process_count"><c>process_count</c></seealso>, + <seealso marker="#system_info_process_limit"><c>process_limit</c></seealso> + </p> + </item> + <tag><seealso marker="#system_info_time"> + <c>System Time</c></seealso></tag> + <item> + <p> + <seealso marker="#system_info_end_time"><c>end_time</c></seealso>, + <seealso marker="#system_info_os_monotonic_time_source"><c>os_monotonic_time_source</c></seealso>, + <seealso marker="#system_info_os_system_time_source"><c>os_system_time_source</c></seealso>, + <seealso marker="#system_info_start_time"><c>start_time</c></seealso>, + <seealso marker="#system_info_time_correction"><c>time_correction</c></seealso>, + <seealso marker="#system_info_time_offset"><c>time_offset</c></seealso>, + <seealso marker="#system_info_time_warp_mode"><c>time_warp_mode</c></seealso>, + <seealso marker="#system_info_tolerant_timeofday"><c>tolerant_timeofday</c></seealso> + </p> + </item> + <tag><seealso marker="#system_info_scheduler"> + <c>Scheduler Information</c></seealso></tag> + <item> + <p> + <seealso marker="#system_info_dirty_cpu_schedulers"><c>dirty_cpu_schedulers</c></seealso>, + <seealso marker="#system_info_dirty_cpu_schedulers_online"><c>dirty_cpu_schedulers_online</c></seealso>, + <seealso marker="#system_info_dirty_io_schedulers"><c>dirty_io_schedulers</c></seealso>, + <seealso marker="#system_info_multi_scheduling"><c>multi_scheduling</c></seealso>, + <seealso marker="#system_info_multi_scheduling_blockers"><c>multi_scheduling_blockers</c></seealso>, + <seealso marker="#system_info_normal_multi_scheduling_blockers"><c>normal_multi_scheduling_blockers</c></seealso>, + <seealso marker="#system_info_scheduler_bind_type"><c>scheduler_bind_type</c></seealso>, + <seealso marker="#system_info_scheduler_bindings"><c>scheduler_bindings</c></seealso>, + <seealso marker="#system_info_scheduler_id"><c>scheduler_id</c></seealso>, + <seealso marker="#system_info_schedulers"><c>schedulers</c></seealso>, + <seealso marker="#system_info_smp_support"><c>smp_support</c></seealso>, + <seealso marker="#system_info_threads"><c>threads</c></seealso>, + <seealso marker="#system_info_thread_pool_size"><c>thread_pool_size</c></seealso> + </p> + </item> + <tag><seealso marker="#system_info_dist"> + <c>Distribution Information</c></seealso></tag> + <item> + <p> + <seealso marker="#system_info_creation"><c>creation</c></seealso>, + <seealso marker="#system_info_delayed_node_table_gc"><c>delayed_node_table_gc</c></seealso>, + <seealso marker="#system_info_dist"><c>dist</c></seealso>, + <seealso marker="#system_info_dist_buf_busy_limit"><c>dist_buf_busy_limit</c></seealso>, + <seealso marker="#system_info_dist_ctrl"><c>dist_ctrl</c></seealso> + </p> + </item> + <tag><seealso marker="#system_info_misc"> + <c>System Information</c></seealso></tag> + <item> + <p> + <seealso marker="#system_info_build_type"><c>build_type</c></seealso>, + <seealso marker="#system_info_c_compiler_used"><c>c_compiler_used</c></seealso>, + <seealso marker="#system_info_check_io"><c>check_io</c></seealso>, + <seealso marker="#system_info_compat_rel"><c>compat_rel</c></seealso>, + <seealso marker="#system_info_debug_compiled"><c>debug_compiled</c></seealso>, + <seealso marker="#system_info_driver_version"><c>driver_version</c></seealso>, + <seealso marker="#system_info_dynamic_trace"><c>dynamic_trace</c></seealso>, + <seealso marker="#system_info_dynamic_trace_probes"><c>dynamic_trace_probes</c></seealso>, + <seealso marker="#system_info_info"><c>info</c></seealso>, + <seealso marker="#system_info_kernel_poll"><c>kernel_poll</c></seealso>, + <seealso marker="#system_info_loaded"><c>loaded</c></seealso>, + <seealso marker="#system_info_machine"><c>machine</c></seealso>, + <seealso marker="#system_info_modified_timing_level"><c>modified_timing_level</c></seealso>, + <seealso marker="#system_info_nif_version"><c>nif_version</c></seealso>, + <seealso marker="#system_info_otp_release"><c>otp_release</c></seealso>, + <seealso marker="#system_info_port_parallelism"><c>port_parallelism</c></seealso>, + <seealso marker="#system_info_system_version"><c>system_version</c></seealso>, + <seealso marker="#system_info_system_architecture"><c>system_architecture</c></seealso>, + <seealso marker="#system_info_trace_control_word"><c>trace_control_word</c></seealso>, + <seealso marker="#system_info_version"><c>version</c></seealso>, + <seealso marker="#system_info_wordsize"><c>wordsize</c></seealso> + </p> + </item> + </taglist> + </desc> + </func> + + <func> + <name name="system_info" arity="1" clause_i="1" + anchor="system_info_allocator" since=""/> <!-- allocated_areas --> + <name name="system_info" arity="1" clause_i="2" since=""/> <!-- allocator --> + <name name="system_info" arity="1" clause_i="3" since=""/> <!-- {allocator, _} --> + <name name="system_info" arity="1" clause_i="4" since=""/> <!-- alloc_util_allocators --> + <name name="system_info" arity="1" clause_i="5" since=""/> <!-- {allocator_sizes, _} --> + <name name="system_info" arity="1" clause_i="27" since=""/> <!-- elib_malloc --> <fsummary>Information about the system allocators.</fsummary> <type variable="Allocator" name_i="2"/> <type variable="Version" name_i="2"/> @@ -7065,12 +7730,13 @@ ok <type variable="Alloc" name_i="3"/> <desc> <marker id="system_info_allocator_tags"></marker> - <p>Returns various information about the allocators of the - current system (emulator) as specified by + <p>Returns various information about the memory allocators + of the current system (emulator) as specified by <c><anno>Item</anno></c>:</p> <marker id="system_info_allocated_areas"></marker> <taglist> - <tag><c>allocated_areas</c></tag> + <tag><marker id="system_info_allocated_areas"/> + <c>allocated_areas</c></tag> <item> <p>Returns a list of tuples with information about miscellaneous allocated memory areas.</p> @@ -7092,9 +7758,9 @@ ok <seealso marker="#memory/0"> <c>erlang:memory/0,1</c></seealso>.</p> </item> - <tag><c>allocator</c></tag> + <tag><marker id="system_info_allocator"/> + <c>allocator</c></tag> <item> - <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"> @@ -7127,19 +7793,9 @@ ok <seealso marker="erts:erts_alloc#flags"> <c>erts_alloc(3)</c></seealso>.</p> </item> - <tag><c>alloc_util_allocators</c></tag> + <tag><marker id="system_info_allocator_tuple"></marker> + <c>{allocator, <anno>Alloc</anno>}</c></tag> <item> - <marker id="system_info_alloc_util_allocators"></marker> - <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 section - <seealso marker="erts:erts_alloc#alloc_util">The - alloc_util framework</seealso> - in <c>erts_alloc(3)</c>.</p> - </item> - <tag><c>{allocator, <anno>Alloc</anno>}</c></tag> - <item> - <marker id="system_info_allocator_tuple"></marker> <p>Returns information about the specified allocator. As from ERTS 5.6.1, the return value is a list of <c>{instance, InstanceNo, InstanceInfo}</c> tuples, @@ -7184,9 +7840,19 @@ ok values. The first value is the memory pool size and the second value is the used memory size.</p> </item> - <tag><c>{allocator_sizes, <anno>Alloc</anno>}</c></tag> + <tag><marker id="system_info_alloc_util_allocators"/> + <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 section + <seealso marker="erts:erts_alloc#alloc_util">The + alloc_util framework</seealso> + in <c>erts_alloc(3)</c>.</p> + </item> + <tag><marker id="system_info_allocator_sizes"/> + <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 @@ -7194,13 +7860,23 @@ ok <c>erlang:system_info({allocator, <anno>Alloc</anno>})</c></seealso>.</p> </item> + <tag><marker id="system_info_elib_malloc"/> + <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>, as the + <c>elib_malloc</c> allocator has been removed.</p> + </item> </taglist> </desc> </func> <func> - <name name="system_info" arity="1" clause_i="10"/> - <name name="system_info" arity="1" clause_i="11"/> + <name name="system_info" arity="1" clause_i="12" + anchor="system_info_cpu_topology" since=""/> <!-- cpu_topology --> + <name name="system_info" arity="1" clause_i="13" since=""/> <!-- {cpu_topology, _} --> + <name name="system_info" arity="1" clause_i="38" since=""/> <!-- logical_processors --> + <name name="system_info" arity="1" clause_i="73" since="?"/> <!-- update_cpu_info --> <fsummary>Information about the CPU topology of the system.</fsummary> <type name="cpu_topology"/> <type name="level_entry"/> @@ -7227,12 +7903,12 @@ ok </type_desc> <desc> <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> + <tag><marker id="system_info_cpu_topology"/> + <c>cpu_topology</c></tag> <item> <p>Returns the <c><anno>CpuTopology</anno></c> currently used by the emulator. The CPU topology is used when binding schedulers @@ -7295,31 +7971,89 @@ ok <seealso marker="#system_info_cpu_topology"> <c>cpu_topology</c></seealso>.</p> </item> + <tag><marker id="system_info_logical_processors"/> + <c>logical_processors</c></tag> + <item> + <p>Returns the detected number of logical processors configured + 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="system_info_logical_processors_available"/> + <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 + cannot detect the available logical processors. The number + of available logical processors is less than or equal to + the number of <seealso marker="#system_info_logical_processors_online"> + logical processors online</seealso>.</p> + </item> + <tag><marker id="system_info_logical_processors_online"/> + <c>logical_processors_online</c></tag> + <item> + <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 cannot + detect logical processors online. The number of logical + processors online is less than or equal to the number of + <seealso marker="#system_info_logical_processors">logical processors + configured</seealso>.</p> + </item> + <tag><marker id="system_info_update_cpu_info"/> + <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 number of logical processors + <seealso marker="#system_info_logical_processors">configured</seealso>, + <seealso marker="#system_info_logical_processors_online">online</seealso>, + and <seealso marker="#system_info_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 + number of schedulers online</seealso>. You typically want + to have as many schedulers online as + <seealso marker="#system_info_logical_processors_available">logical + processors available</seealso>.</p> + </item> </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"/> + <name name="system_info" arity="1" clause_i="31" + anchor="system_info_process" since="?"/> <!-- fullsweep_after --> + <name name="system_info" arity="1" clause_i="32" since=""/> <!-- garbage_collection --> + <name name="system_info" arity="1" clause_i="33" since=""/> <!-- heap_sizes --> + <name name="system_info" arity="1" clause_i="34" since=""/> <!-- heap_type --> + <name name="system_info" arity="1" clause_i="40" since="?"/> <!-- max_heap_size --> + <name name="system_info" arity="1" clause_i="41" since="?"/> <!-- message_queue_data --> + <name name="system_info" arity="1" clause_i="42" since="?"/> <!-- min_heap_size --> + <name name="system_info" arity="1" clause_i="43" since="?"/> <!-- min_bin_vheap_size --> + <name name="system_info" arity="1" clause_i="57" since=""/> <!-- procs --> <fsummary>Information about the default process heap settings.</fsummary> <type name="message_queue_data"/> <type name="max_heap_size"/> <desc> + <marker id="system_info_process_tags"/> <p>Returns information about the default process heap settings:</p> <taglist> - <tag><c>fullsweep_after</c></tag> + <tag><marker id="system_info_fullsweep_after"/> + <c>fullsweep_after</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> + <tag><marker id="system_info_garbage_collection"/> + <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 @@ -7332,7 +8066,30 @@ ok can spawn a process that does not use the default settings.</p> </item> - <tag><c>max_heap_size</c></tag> + <tag><marker id="system_info_heap_sizes"/> + <c>heap_sizes</c></tag> + <item> + <p>Returns a list of integers representing valid heap sizes + in words. All Erlang heaps are sized from sizes in this + list.</p> + </item> + <tag><marker id="system_info_heap_type"/> + <c>heap_type</c></tag> + <item> + <p>Returns the heap type used by the current emulator. One + heap type exists:</p> + <taglist> + <tag><c>private</c></tag> + <item> + Each process has a heap reserved for its use and no + references between heaps of different processes are + allowed. Messages passed between processes are copied + between heaps. + </item> + </taglist> + </item> + <tag><marker id="system_info_max_heap_size"/> + <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 @@ -7348,12 +8105,6 @@ ok 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> @@ -7366,155 +8117,366 @@ ok <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> + <tag><marker id="system_info_min_heap_size"/> + <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_min_bin_vheap_size"/> + <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><marker id="system_info_procs"/> + <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 section <seealso marker="erts:crash_dump"> + How to interpret the Erlang crash dumps</seealso> + in the User's Guide.</p> + </item> </taglist> </desc> </func> <func> - <name name="system_info" arity="1" clause_i="6"/> - <name name="system_info" arity="1" clause_i="7"/> - <name name="system_info" arity="1" clause_i="8"/> - <name name="system_info" arity="1" clause_i="9"/> - <name name="system_info" arity="1" clause_i="12"/> - <name name="system_info" arity="1" clause_i="13"/> - <name name="system_info" arity="1" clause_i="14"/> - <name name="system_info" arity="1" clause_i="15"/> - <name name="system_info" arity="1" clause_i="16"/> - <name name="system_info" arity="1" clause_i="17"/> - <name name="system_info" arity="1" clause_i="18"/> - <name name="system_info" arity="1" clause_i="19"/> - <name name="system_info" arity="1" clause_i="20"/> - <name name="system_info" arity="1" clause_i="21"/> - <name name="system_info" arity="1" clause_i="22"/> - <name name="system_info" arity="1" clause_i="23"/> - <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="29"/> - <name name="system_info" arity="1" clause_i="30"/> - <name name="system_info" arity="1" clause_i="31"/> - <name name="system_info" arity="1" clause_i="32"/> - <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="40"/> - <name name="system_info" arity="1" clause_i="41"/> - <name name="system_info" arity="1" clause_i="42"/> - <name name="system_info" arity="1" clause_i="43"/> - <name name="system_info" arity="1" clause_i="44"/> - <name name="system_info" arity="1" clause_i="45"/> - <name name="system_info" arity="1" clause_i="46"/> - <name name="system_info" arity="1" clause_i="47"/> - <name name="system_info" arity="1" clause_i="48"/> - <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"/> - <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> + <name name="system_info" arity="1" clause_i="6" anchor="system_info_limits" since="?"/> <!-- atom_count --> + <name name="system_info" arity="1" clause_i="7" since="?"/> <!-- atom_limit --> + <name name="system_info" arity="1" clause_i="29" since="?"/> <!-- ets_count --> + <name name="system_info" arity="1" clause_i="30" since="?"/> <!-- ets_limit --> + <name name="system_info" arity="1" clause_i="53" since="?"/> <!-- port_count --> + <name name="system_info" arity="1" clause_i="54" since="?"/> <!-- port_limit --> + <name name="system_info" arity="1" clause_i="55" since=""/> <!-- process_count --> + <name name="system_info" arity="1" clause_i="56" since=""/> <!-- process_limit --> + <fsummary>Information about various system limits.</fsummary> <desc> - <p>Returns various information about the current system - (emulator) as specified by <c><anno>Item</anno></c>:</p> + <marker id="system_info_limits"/> + <p>Returns information about the current system + (emulator) limits as specified by <c><anno>Item</anno></c>:</p> <taglist> - <tag><c>allocated_areas</c>, <c>allocator</c>, - <c>alloc_util_allocators</c>, <c>allocator_sizes</c></tag> + <tag><marker id="system_info_atom_count"/> + <c>atom_count</c></tag> <item> - <p>See <seealso marker="#system_info_allocator_tags"> - above</seealso>.</p> + <p>Returns the number of atoms currently existing at the + local node. The value is given as an integer.</p> </item> - <tag><c>build_type</c></tag> + <tag><marker id="system_info_atom_limit"/> + <c>atom_limit</c></tag> <item> - <p>Returns an atom describing the build type of the runtime - system. This is normally the atom <c>opt</c> for optimized. - 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 - can be added or removed at any time without prior notice.</p> + <p>Returns the maximum number of atoms allowed. + This limit can be increased at startup by passing + command-line flag + <seealso marker="erts:erl#+t"><c>+t</c></seealso> to + <c>erl(1)</c>. + </p> </item> - <tag><c>c_compiler_used</c></tag> + <tag><marker id="system_info_ets_count"/> + <c>ets_count</c></tag> <item> - <p>Returns a two-tuple describing the C compiler used when - 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> + <p>Returns the number of ETS tables currently existing at the + local node.</p> </item> - <tag><c>check_io</c></tag> + <tag><marker id="system_info_ets_limit"/> + <c>ets_limit</c></tag> <item> - <p>Returns a list containing miscellaneous information - 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> + <p>Returns the limit for number of ETS tables. This limit is + <seealso marker="stdlib:ets#max_ets_tables">partially obsolete</seealso> + and number of tables are only limited by available memory.</p> </item> - <tag><c>compat_rel</c></tag> + <tag><marker id="system_info_port_count"/><c>port_count</c></tag> <item> - <p>Returns the compatibility mode of the local node as - an integer. The integer returned represents the - 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 command-line flag - <seealso marker="erts:erl#compat_rel"><c>+R</c></seealso> in - <c>erl(1)</c>.</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><c>cpu_topology</c></tag> + <tag><marker id="system_info_port_limit"/> + <c>port_limit</c></tag> <item> - <p>See <seealso - marker="#system_info_cpu_topology_tags">above</seealso>.</p> + <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 command-line flag + <seealso marker="erl#+Q"><c>+Q</c></seealso> in <c>erl(1)</c>.</p> </item> - <tag><c>creation</c></tag> + <tag><marker id="system_info_process_count"/> + <c>process_count</c></tag> <item> - <p>Returns the creation of the local node as an integer. - The creation is changed when a node is restarted. The - 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. 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> + <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><c>debug_compiled</c></tag> + <tag><marker id="system_info_process_limit"/> + <c>process_limit</c></tag> <item> - <p>Returns <c>true</c> if the emulator has been - debug-compiled, otherwise <c>false</c>.</p> + <p>Returns the maximum number of simultaneously existing + 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"><c>+P</c></seealso> + in <c>erl(1)</c>.</p> </item> - <tag><c>delayed_node_table_gc</c></tag> + </taglist> + </desc> + </func> + + <func> + <name name="system_info" arity="1" clause_i="26" + anchor="system_info_time" since="OTP 18.0"/> <!-- end_time --> + <name name="system_info" arity="1" clause_i="50" since="OTP 18.0"/> <!-- os_monotonic_time_source --> + <name name="system_info" arity="1" clause_i="51" since="OTP 18.0"/> <!-- os_system_time_source --> + <name name="system_info" arity="1" clause_i="63" since="OTP 18.0"/> <!-- start_time --> + <name name="system_info" arity="1" clause_i="68" since="OTP 18.0"/> <!-- time_correction --> + <name name="system_info" arity="1" clause_i="69" since="OTP 18.0"/> <!-- time_offset --> + <name name="system_info" arity="1" clause_i="70" since="OTP 18.0"/> <!-- time_warp_mode --> + <name name="system_info" arity="1" clause_i="71" since="?"/> <!-- tolerant_timeofday --> + <fsummary>Information about system time.</fsummary> + <desc> + <marker id="system_info_time_tags"/> + <p>Returns information about the current system + (emulator) time as specified by <c><anno>Item</anno></c>:</p> + <taglist> + <tag><marker id="system_info_end_time"/><c>end_time</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 command-line flag - <seealso marker="erts:erl#+zdntgc"><c>+zdntgc</c></seealso> - to <c>erl(1)</c>. For more information, see the documentation of - the command-line flag.</p> + <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>dirty_cpu_schedulers</c></tag> + <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 exists if OS monotonic time is + available to the runtime system.</p> + </item> + <tag><c>{clock_id, ClockId}</c></tag> + <item><p>This tuple only exists 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>. Notice that + the resolution does not say anything about the + <seealso marker="time_correction#Time_Accuracy"> + accuracy</seealso> or whether the + <seealso marker="time_correction#Time_Precision"> + precision</seealso> aligns 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 must 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 must 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 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>Exists only 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 can be lower than + <c>OsSystemTimeResolution</c>. Notice that + the resolution does not say anything about the + <seealso marker="time_correction#Time_Accuracy"> + accuracy</seealso> or 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_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.</p> + <p>See also <seealso marker="#system_info_end_time"> + <c>erlang:system_info(end_time)</c></seealso>.</p> + </item> + <tag><marker id="system_info_time_correction"/> + <c>time_correction</c></tag> + <item> + <p>Returns a boolean value indicating whether + <seealso marker="time_correction#Time_Correction"> + time correction</seealso> is enabled or not.</p> + </item> + <tag><marker id="system_info_time_offset"/> + <c>time_offset</c></tag> + <item> + <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 + and finalized later. 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> that is used:</p> + <taglist> + <tag><c>no_time_warp</c></tag> + <item>The <seealso marker="time_correction#No_Time_Warp_Mode"> + no time warp mode</seealso> is used. + </item> + <tag><c>single_time_warp</c></tag> + <item>The <seealso marker="time_correction#Single_Time_Warp_Mode"> + single time warp mode</seealso> is used. + </item> + <tag><c>multi_time_warp</c></tag> + <item>The <seealso marker="time_correction#Multi_Time_Warp_Mode"> + multi-time warp mode</seealso> is used. + </item> + </taglist> + </item> + <tag><marker id="system_info_tolerant_timeofday"/> + <c>tolerant_timeofday</c></tag> + <item> + <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> + </taglist> + </desc> + </func> + + <func> + <name name="system_info" arity="1" clause_i="17" + anchor="system_info_scheduler" since="?"/> <!-- dirty_cpu_schedulers --> + <name name="system_info" arity="1" clause_i="18" since="?"/> <!-- dirty_cpu_schedulers_online --> + <name name="system_info" arity="1" clause_i="19" since="?"/> <!-- dirty_io_schedulers --> + <name name="system_info" arity="1" clause_i="45" since=""/> <!-- multi_scheduling --> + <name name="system_info" arity="1" clause_i="46" since=""/> <!-- multi_scheduling_blockers --> + <name name="system_info" arity="1" clause_i="49" since="?"/> <!-- normal_multi_scheduling_blockers --> + <name name="system_info" arity="1" clause_i="58" since=""/> <!-- scheduler_bind_type --> + <name name="system_info" arity="1" clause_i="59" since=""/> <!-- scheduler_bindings --> + <name name="system_info" arity="1" clause_i="60" since=""/> <!-- scheduler_id --> + <name name="system_info" arity="1" clause_i="61" since=""/> <!-- schedulers --> + <name name="system_info" arity="1" clause_i="62" since=""/> <!-- smp_support --> + <name name="system_info" arity="1" clause_i="66" since=""/> <!-- threads --> + <name name="system_info" arity="1" clause_i="67" since=""/> <!-- thread_pool_size --> + <fsummary>Information about system schedulers.</fsummary> + <desc> + <marker id="system_info_scheduler_tags"/> + <p>Returns information about schedulers, scheduling and threads in the + current system as specified by <c><anno>Item</anno></c>:</p> + <taglist> + <tag><marker id="system_info_dirty_cpu_schedulers"/> + <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, @@ -7529,9 +8491,6 @@ ok <seealso marker="erts:erl#+SDcpu"><c>+SDcpu</c></seealso> or <seealso marker="erts:erl#+SDPcpu"><c>+SDPcpu</c></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"> <c>erlang:system_flag(dirty_cpu_schedulers_online, @@ -7548,9 +8507,9 @@ ok <c>erlang:system_flag(schedulers_online, SchedulersOnline)</c></seealso>.</p> </item> - <tag><c>dirty_cpu_schedulers_online</c></tag> + <tag><marker id="system_info_dirty_cpu_schedulers_online"/> + <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>, @@ -7561,9 +8520,6 @@ ok startup by passing command-line flag <seealso marker="erts:erl#+SDcpu"><c>+SDcpu</c></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"> <c>erlang:system_info(dirty_cpu_schedulers)</c></seealso>, @@ -7575,9 +8531,9 @@ ok <c>erlang:system_flag(dirty_cpu_schedulers_online, DirtyCPUSchedulersOnline)</c></seealso>.</p> </item> - <tag><c>dirty_io_schedulers</c></tag> + <tag><marker id="system_info_dirty_io_schedulers"/> + <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 @@ -7585,9 +8541,6 @@ ok <p>This value can be set at startup by passing command-line argument <seealso marker="erts:erl#+SDio"><c>+SDio</c></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"> <c>erlang:system_info(dirty_cpu_schedulers)</c></seealso>, @@ -7597,195 +8550,14 @@ ok <c>erlang:system_flag(dirty_cpu_schedulers_online, DirtyCPUSchedulersOnline)</c></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 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"><c>+zdbbl</c></seealso> - to <c>erl(1)</c>.</p> - </item> - <tag><c>dist_ctrl</c></tag> - <item> - <p>Returns a list of tuples - <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 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 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 - <seealso marker="runtime_tools:dyntrace"> - <c>dyntrace(3)</c></seealso> manual page and the - <c>README.dtrace</c>/<c>README.systemtap</c> files in the - 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 (<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>, as the - <c>elib_malloc</c> allocator has been removed.</p> - </item> - <tag><marker id="system_info_eager_check_io"/> - <c>eager_check_io</c></tag> - <item> - <p>Returns the value of command-line flag - <seealso marker="erl#+secio"><c>+secio</c></seealso> in - <c>erl(1)</c>, which is either <c>true</c> or <c>false</c>. - For information about the different values, see the - documentation of the command-line flag.</p> - </item> - <tag><c>ets_limit</c></tag> - <item> - <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"><c>+e</c></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> - <p>Returns a list of integers representing valid heap sizes - in words. All Erlang heaps are sized from sizes in this - list.</p> - </item> - <tag><c>heap_type</c></tag> - <item> - <p>Returns the heap type used by the current emulator. One - heap type exists:</p> - <taglist> - <tag><c>private</c></tag> - <item> - Each process has a heap reserved for its use and no - references between heaps of different processes are - allowed. Messages passed between processes are copied - between heaps. - </item> - </taglist> - </item> - <tag><c>info</c></tag> - <item> - <p>Returns a binary containing a string of miscellaneous - system information formatted as in Erlang crash dumps. - 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> - </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 section - <seealso marker="erts:crash_dump">How to interpret the Erlang - crash dumps</seealso> in the User's Guide.</p> - </item> - <tag><c>logical_processors</c></tag> + <tag><marker id="system_info_multi_scheduling"/> + <c>multi_scheduling</c></tag> <item> - <marker id="logical_processors"></marker> - <p>Returns the detected number of logical processors configured - 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><c>logical_processors_available</c></tag> - <item> - <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><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 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> - </item> - <tag><c>machine</c></tag> - <item> - <p>Returns a string containing the Erlang machine name.</p> - </item> - <tag><c>modified_timing_level</c></tag> - <item> - <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"><c>+T</c></seealso> - in <c>erl(1)</c></p> - </item> - <tag><c>multi_scheduling</c></tag> - <item> - <marker id="system_info_multi_scheduling"></marker> <p>Returns one of the following:</p> <taglist> <tag><c>disabled</c></tag> <item> - <p>The emulator has only one scheduler thread. The - emulator does not have SMP support, or have been - started with only one scheduler thread.</p> + <p>The emulator has been started with only one scheduler thread.</p> </item> <tag><c>blocked</c></tag> <item> @@ -7820,9 +8592,9 @@ ok and <seealso marker="#system_info_schedulers"> <c>erlang:system_info(schedulers)</c></seealso>.</p> </item> - <tag><c>multi_scheduling_blockers</c></tag> + <tag><marker id="system_info_multi_scheduling_blockers"/> + <c>multi_scheduling_blockers</c></tag> <item> - <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 @@ -7840,15 +8612,9 @@ ok and <seealso marker="#system_info_schedulers"> <c>erlang:system_info(schedulers)</c></seealso>.</p> </item> - <tag><c>nif_version</c></tag> + <tag><marker id="system_info_normal_multi_scheduling_blockers"/> + <c>normal_multi_scheduling_blockers</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 (that is, all normal schedulers but one is blocked), otherwise the empty list is returned. @@ -7866,192 +8632,9 @@ ok and <seealso marker="#system_info_schedulers"> <c>erlang:system_info(schedulers)</c></seealso>.</p> </item> - <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 ERTS application - is part of.</p> - <p>As from Erlang/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 exists if OS monotonic time is - available to the runtime system.</p> - </item> - <tag><c>{clock_id, ClockId}</c></tag> - <item><p>This tuple only exists 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>. Notice that - the resolution does not say anything about the - <seealso marker="time_correction#Time_Accuracy"> - accuracy</seealso> or whether the - <seealso marker="time_correction#Time_Precision"> - precision</seealso> aligns 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 must 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 must 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 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>Exists only 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 can be lower than - <c>OsSystemTimeResolution</c>. Notice that - the resolution does not say anything about the - <seealso marker="time_correction#Time_Accuracy"> - accuracy</seealso> or 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><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"><c>+spp</c></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. 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><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 command-line flag - <seealso marker="erl#+Q"><c>+Q</c></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. 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><c>process_limit</c></tag> + <tag><marker id="system_info_scheduler_bind_type"/> + <c>scheduler_bind_type</c></tag> <item> - <marker id="system_info_process_limit"></marker> - <p>Returns the maximum number of simultaneously existing - 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"><c>+P</c></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 section <seealso marker="erts:crash_dump"> - How to interpret the Erlang crash dumps</seealso> - in the User's Guide.</p> - </item> - <tag><c>scheduler_bind_type</c></tag> - <item> - <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>Notice that although a user has requested @@ -8065,9 +8648,9 @@ ok <seealso marker="#system_info_scheduler_bindings"> <c>erlang:system_info(scheduler_bindings)</c></seealso>.</p> </item> - <tag><c>scheduler_bindings</c></tag> + <tag><marker id="system_info_scheduler_bindings"/> + <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 @@ -8091,9 +8674,9 @@ ok <seealso marker="#system_info_schedulers_online"> <c>erlang:system_info(schedulers_online)</c></seealso>.</p> </item> - <tag><c>scheduler_id</c></tag> + <tag><marker id="system_info_scheduler_id"/> + <c>scheduler_id</c></tag> <item> - <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, @@ -8103,9 +8686,9 @@ ok <seealso marker="#system_info_schedulers"> <c>erlang:system_info(schedulers)</c></seealso>.</p> </item> - <tag><c>schedulers</c></tag> + <tag><marker id="system_info_schedulers"/> + <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 @@ -8132,9 +8715,9 @@ ok <c>erlang:system_info(multi_scheduling_blockers)</c></seealso>. </p> </item> - <tag><c>schedulers_online</c></tag> + <tag><marker id="system_info_schedulers_online"/> + <c>schedulers_online</c></tag> <item> - <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 <= @@ -8146,36 +8729,18 @@ ok <c>erlang:system_flag(schedulers_online, SchedulersOnline)</c></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> 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.</p> - <p>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> - </item> - <tag><c>system_architecture</c></tag> + <tag><marker id="system_info_smp_support"/> + <c>smp_support</c></tag> <item> - <p>Returns a string containing the processor and OS - architecture the emulator is built for.</p> + <p>Returns <c>true</c>.</p> </item> - <tag><c>threads</c></tag> + <tag><marker id="system_info_threads"/> + <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> + <p>Returns <c>true</c>.</p> </item> - <tag><c>thread_pool_size</c></tag> + <tag><marker id="system_info_thread_pool_size"/> + <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 @@ -8184,111 +8749,342 @@ ok <c>erl_driver:driver_async()</c></seealso>). The value is given as an integer.</p> </item> - <tag><c>time_correction</c></tag> + </taglist> + </desc> + </func> + + <func> + <name name="system_info" arity="1" clause_i="14" + anchor="system_info_dist" since=""/> <!-- creation --> + <name name="system_info" arity="1" clause_i="16" since="?"/> <!-- delayed_node_table_gc --> + <name name="system_info" arity="1" clause_i="20" since=""/> <!-- dist --> + <name name="system_info" arity="1" clause_i="21" since="?"/> <!-- dist_buf_busy_limit --> + <name name="system_info" arity="1" clause_i="22" since=""/> <!-- dist_ctrl --> + <fsummary>Information about erlang distribution.</fsummary> + <desc> + <marker id="system_info_dist_tags"/> + <p>Returns information about Erlang Distribution in the + current system as specified by <c><anno>Item</anno></c>:</p> + <taglist> + <tag><marker id="system_info_creation"/> + <c>creation</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> + <p>Returns the creation of the local node as an integer. + The creation is changed when a node is restarted. The + 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. 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>time_offset</c></tag> + <tag><marker id="system_info_delayed_node_table_gc"/> + <c>delayed_node_table_gc</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 - and finalized later. 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> + <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 command-line flag + <seealso marker="erts:erl#+zdntgc"><c>+zdntgc</c></seealso> + to <c>erl(1)</c>. For more information, see the documentation of + the command-line flag.</p> </item> - <tag><marker id="system_info_time_warp_mode"/> - <c>time_warp_mode</c></tag> + <tag><marker id="system_info_dist"/> + <c>dist</c></tag> <item> - <p>Returns a value identifying the - <seealso marker="time_correction#Time_Warp_Modes"> - time warp mode</seealso> that is used:</p> - <taglist> - <tag><c>no_time_warp</c></tag> - <item>The <seealso marker="time_correction#No_Time_Warp_Mode"> - no time warp mode</seealso> is used. - </item> - <tag><c>single_time_warp</c></tag> - <item>The <seealso marker="time_correction#Single_Time_Warp_Mode"> - single time warp mode</seealso> is used. - </item> - <tag><c>multi_time_warp</c></tag> - <item>The <seealso marker="time_correction#Multi_Time_Warp_Mode"> - multi-time warp mode</seealso> is used. - </item> - </taglist> + <p>Returns a binary containing a string of distribution + information formatted as in Erlang crash dumps. 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>tolerant_timeofday</c></tag> + <tag><marker id="system_info_dist_buf_busy_limit"/> + <c>dist_buf_busy_limit</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> + <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"><c>+zdbbl</c></seealso> + to <c>erl(1)</c>.</p> </item> - <tag><c>trace_control_word</c></tag> + <tag><marker id="system_info_dist_ctrl"/> + <c>dist_ctrl</c></tag> + <item> + <p>Returns a list of tuples + <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> + </taglist> + </desc> + </func> + + <func> + <!-- <name name="system_info" arity="1" clause_i="1"/> allocated_areas --> + <!-- <name name="system_info" arity="1" clause_i="2"/> allocated --> + <!-- <name name="system_info" arity="1" clause_i="3"/> {allocator, _} --> + <!-- <name name="system_info" arity="1" clause_i="4"/> alloc_util_allocators --> + <!-- <name name="system_info" arity="1" clause_i="5"/> {allocator_sizes, _} --> + <!-- <name name="system_info" arity="1" clause_i="6"/> atom_count --> + <!-- <name name="system_info" arity="1" clause_i="7"/> atom_limit --> + <name name="system_info" arity="1" clause_i="8" + anchor="system_info_misc" since="?"/> <!-- build_type --> + <name name="system_info" arity="1" clause_i="9" since=""/> <!-- c_compiler_used --> + <name name="system_info" arity="1" clause_i="10" since=""/> <!-- check_io --> + <name name="system_info" arity="1" clause_i="11" since=""/> <!-- compat_rel --> + <!-- <name name="system_info" arity="1" clause_i="12"/> cpu_topology --> + <!-- <name name="system_info" arity="1" clause_i="13"/> {cpu_topology, _} --> + <!-- <name name="system_info" arity="1" clause_i="14"/> creation --> + <name name="system_info" arity="1" clause_i="15" since=""/> <!-- debug_compiled --> + <!-- <name name="system_info" arity="1" clause_i="16"/> delayed_node_table_gc --> + <!-- <name name="system_info" arity="1" clause_i="17"/> dirty_cpu_schedulers --> + <!-- <name name="system_info" arity="1" clause_i="18"/> dirty_cpu_schedulers_online --> + <!-- <name name="system_info" arity="1" clause_i="19"/> dirty_io_schedulers --> + <!-- <name name="system_info" arity="1" clause_i="20"/> dist --> + <!-- <name name="system_info" arity="1" clause_i="21"/> dist_buf_busy_limit --> + <!-- <name name="system_info" arity="1" clause_i="22"/> dist_ctrl --> + <name name="system_info" arity="1" clause_i="23" since=""/> <!-- driver_version --> + <name name="system_info" arity="1" clause_i="24" since="?"/> <!-- dynamic_trace --> + <name name="system_info" arity="1" clause_i="25" since="?"/> <!-- dynamic_trace_probes --> + <!-- <name name="system_info" arity="1" clause_i="26"/> end_time --> + <!-- <name name="system_info" arity="1" clause_i="27"/> elib_malloc --> + <!-- <name name="system_info" arity="1" clause_i="28"/> eager_check_io, removed --> + <!-- <name name="system_info" arity="1" clause_i="29"/> ets_count --> + <!-- <name name="system_info" arity="1" clause_i="30"/> ets_limit --> + <!-- <name name="system_info" arity="1" clause_i="31"/> fullsweep_after --> + <!-- <name name="system_info" arity="1" clause_i="32"/> garbage_collection --> + <!-- <name name="system_info" arity="1" clause_i="33"/> heap_sizes --> + <!-- <name name="system_info" arity="1" clause_i="34"/> heap_type --> + <name name="system_info" arity="1" clause_i="35" since=""/> <!-- info --> + <name name="system_info" arity="1" clause_i="36" since=""/> <!-- kernel_poll --> + <name name="system_info" arity="1" clause_i="37" since=""/> <!-- loaded --> + <!-- <name name="system_info" arity="1" clause_i="38"/> logical_processors --> + <name name="system_info" arity="1" clause_i="39" since=""/> <!-- machine --> + <!-- <name name="system_info" arity="1" clause_i="40"/> max_heap_size --> + <!-- <name name="system_info" arity="1" clause_i="41"/> message_queue_data --> + <!-- <name name="system_info" arity="1" clause_i="42"/> min_heap_size --> + <!-- <name name="system_info" arity="1" clause_i="43"/> min_bin_vheap_size --> + <name name="system_info" arity="1" clause_i="44" since=""/> <!-- modified_timing_level --> + <!-- <name name="system_info" arity="1" clause_i="45"/> multi_scheduling --> + <!-- <name name="system_info" arity="1" clause_i="46"/> multi_scheduling_blockers --> + <name name="system_info" arity="1" clause_i="47" since="?"/> <!-- nif_version --> + <!-- n<name name="system_info" arity="1" clause_i="48"/> ormal_multi_scheduling_blockers --> + <name name="system_info" arity="1" clause_i="49" since=""/> <!-- otp_release --> + <!-- <name name="system_info" arity="1" clause_i="50"/> os_monotonic_time_source --> + <!-- <name name="system_info" arity="1" clause_i="51"/> os_system_time_source --> + <name name="system_info" arity="1" clause_i="52" since="?"/> <!-- port_parallelism --> + <!-- <name name="system_info" arity="1" clause_i="53"/> port_count --> + <!-- <name name="system_info" arity="1" clause_i="54"/> port_limit --> + <!-- <name name="system_info" arity="1" clause_i="55"/> process_count --> + <!-- <name name="system_info" arity="1" clause_i="56"/> process_limit --> + <!-- <name name="system_info" arity="1" clause_i="57"/> procs --> + <!-- <name name="system_info" arity="1" clause_i="58"/> scheduler_bind_type --> + <!-- <name name="system_info" arity="1" clause_i="59"/> scheduler_bindings --> + <!-- <name name="system_info" arity="1" clause_i="60"/> scheduler_id --> + <!-- <name name="system_info" arity="1" clause_i="61"/> schedulers --> + <!-- <name name="system_info" arity="1" clause_i="62"/> smp_support --> + <!-- <name name="system_info" arity="1" clause_i="63"/> start_time --> + <name name="system_info" arity="1" clause_i="64" since=""/> <!-- system_version --> + <name name="system_info" arity="1" clause_i="65" since=""/> <!-- system_architecture --> + <!-- <name name="system_info" arity="1" clause_i="66"/> threads --> + <!-- <name name="system_info" arity="1" clause_i="67"/> thread_pool_size --> + <!-- <name name="system_info" arity="1" clause_i="68"/> time_correction --> + <!-- <name name="system_info" arity="1" clause_i="69"/> time_offset --> + <!-- <name name="system_info" arity="1" clause_i="70"/> time_warp_mode --> + <!-- <name name="system_info" arity="1" clause_i="71"/> tolerant_timeofday --> + <name name="system_info" arity="1" clause_i="72" since=""/> <!-- trace_control_word --> + <!-- <name name="system_info" arity="1" clause_i="73"/> update_cpu_info --> + <name name="system_info" arity="1" clause_i="74" since=""/> <!-- version --> + <name name="system_info" arity="1" clause_i="75" since=""/> <!-- wordsize --> + <!-- <name name="system_info" arity="1" clause_i="76"/> overview --> + <fsummary>Information about the system.</fsummary> + <desc> + <marker id="system_info_misc_tags"/> + <p>Returns various information about the current system + (emulator) as specified by <c><anno>Item</anno></c>:</p> + <taglist> + <tag><marker id="system_info_build_type"/> + <c>build_type</c></tag> + <item> + <p>Returns an atom describing the build type of the runtime + system. This is normally the atom <c>opt</c> for optimized. + 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 + can be added or removed at any time without prior notice.</p> + </item> + <tag><marker id="system_info_c_compiler_used"/> + <c>c_compiler_used</c></tag> + <item> + <p>Returns a two-tuple describing the C compiler used when + 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> + </item> + <tag><marker id="system_info_check_io"/> + <c>check_io</c></tag> + <item> + <p>Returns a list containing miscellaneous information + 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><marker id="system_info_compat_rel"/> + <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 that the current emulator has been + set to be backward compatible with. The compatibility + mode can be configured at startup by using command-line flag + <seealso marker="erts:erl#compat_rel"><c>+R</c></seealso> in + <c>erl(1)</c>.</p> + </item> + <tag><marker id="system_info_debug_compiled"/> + <c>debug_compiled</c></tag> + <item> + <p>Returns <c>true</c> if the emulator has been + debug-compiled, otherwise <c>false</c>.</p> + </item> + <tag><marker id="system_info_driver_version"/> + <c>driver_version</c></tag> + <item> + <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><marker id="system_info_dynamic_trace"/> + <c>dynamic_trace</c></tag> + <item> + <p>Returns an atom describing the dynamic trace framework + 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 + <seealso marker="runtime_tools:dyntrace"> + <c>dyntrace(3)</c></seealso> manual page and the + <c>README.dtrace</c>/<c>README.systemtap</c> files in the + Erlang source code top directory.</p> + </item> + <tag><marker id="system_info_dynamic_trace_probes"/> + <c>dynamic_trace_probes</c></tag> + <item> + <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_info"/> + <c>info</c></tag> + <item> + <p>Returns a binary containing a string of miscellaneous + system information formatted as in Erlang crash dumps. + 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><marker id="system_info_kernel_poll"/> + <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> + </item> + <tag><marker id="system_info_loaded"/> + <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 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_machine"/> + <c>machine</c></tag> + <item> + <p>Returns a string containing the Erlang machine name.</p> + </item> + <tag><marker id="system_info_modified_timing_level"/> + <c>modified_timing_level</c></tag> + <item> + <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"><c>+T</c></seealso> + in <c>erl(1)</c></p> + </item> + <tag><marker id="system_info_nif_version"/> + <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><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 ERTS application + is part of.</p> + <p>As from Erlang/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_port_parallelism"/> + <c>port_parallelism</c></tag> + <item> + <p>Returns the default port parallelism scheduling hint used. + For more information, see command-line argument + <seealso marker="erl#+spp"><c>+spp</c></seealso> + in <c>erl(1)</c>.</p> + </item> + <tag><marker id="system_info_system_version"/> + <c>system_version</c></tag> + <item> + <p>Returns a string containing version number and + some important properties, such as the number of schedulers.</p> + </item> + <tag><marker id="system_info_system_architecture"/> + <c>system_architecture</c></tag> + <item> + <p>Returns a string containing the processor and OS + architecture the emulator is built for.</p> + </item> + <tag><marker id="system_info_trace_control_word"/> + <c>trace_control_word</c></tag> <item> <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><c>update_cpu_info</c></tag> - <item> - <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>.</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 - 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><c>version</c></tag> + <tag><marker id="system_info_version"/> + <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> + <tag><marker id="system_info_wordsize"/> + <c>wordsize</c></tag> <item> <p>Same as <c>{wordsize, internal}</c>.</p> </item> @@ -8310,18 +9106,11 @@ ok 64-bit architecture, 8 is returned.</p> </item> </taglist> - <note> - <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 ERTS 5.5 and renamed in - ERTS 5.5.1.</p> - </note> </desc> </func> <func> - <name name="system_monitor" arity="0"/> + <name name="system_monitor" arity="0" since=""/> <fsummary>Current system performance monitoring settings.</fsummary> <type name="system_monitor_option"/> <desc> @@ -8335,7 +9124,7 @@ ok </func> <func> - <name name="system_monitor" arity="1"/> + <name name="system_monitor" arity="1" since=""/> <fsummary>Set or clear system performance monitoring options.</fsummary> <type name="system_monitor_option"/> <desc> @@ -8353,7 +9142,7 @@ ok </func> <func> - <name name="system_monitor" arity="2"/> + <name name="system_monitor" arity="2" since=""/> <fsummary>Set system performance monitoring options.</fsummary> <type name="system_monitor_option"/> <desc> @@ -8485,7 +9274,7 @@ ok </func> <func> - <name name="system_profile" arity="0"/> + <name name="system_profile" arity="0" since=""/> <fsummary>Current system profiling settings.</fsummary> <type name="system_profile_option"/> <desc> @@ -8500,7 +9289,7 @@ ok </func> <func> - <name name="system_profile" arity="2"/> + <name name="system_profile" arity="2" since=""/> <fsummary>Current system profiling settings.</fsummary> <type name="system_profile_option"/> <desc> @@ -8561,7 +9350,7 @@ ok <c>erlang:now()</c>. This is also the default if no time stamp flag is specified. If <c>cpu_timestamp</c> has been enabled through - <seealso marker="erlang:trace/3"><c>erlang:trace/3</c></seealso>, + <seealso marker="#trace/3"><c>erlang:trace/3</c></seealso>, this also effects the time stamp produced in profiling messages when flag <c>timestamp</c> is enabled.</p> </item> @@ -8574,7 +9363,7 @@ ok </func> <func> - <name name="system_time" arity="0"/> + <name name="system_time" arity="0" since="OTP 18.0"/> <fsummary>Current Erlang system time.</fsummary> <desc> <p>Returns current @@ -8596,7 +9385,7 @@ ok </func> <func> - <name name="system_time" arity="1"/> + <name name="system_time" arity="1" since="OTP 18.0"/> <fsummary>Current Erlang system time.</fsummary> <desc> <p>Returns current @@ -8618,7 +9407,7 @@ ok </func> <func> - <name name="term_to_binary" arity="1"/> + <name name="term_to_binary" arity="1" since=""/> <fsummary>Encode a term to an Erlang external term format binary. </fsummary> <desc> @@ -8638,11 +9427,15 @@ hello </pre> <p>See also <seealso marker="#binary_to_term/1"> <c>binary_to_term/1</c></seealso>.</p> + <note> + <p>There is no guarantee that this function will return + the same encoded representation for the same term.</p> + </note> </desc> </func> <func> - <name name="term_to_binary" arity="2"/> + <name name="term_to_binary" arity="2" since=""/> <fsummary>Encode a term to en Erlang external term format binary. </fsummary> <desc> @@ -8671,25 +9464,43 @@ hello <p>Option <c>{minor_version, <anno>Version</anno>}</c> can be used to control some encoding details. This option was introduced in Erlang/OTP R11B-4. - The valid values for <c><anno>Version</anno></c> are - <c>0</c> and <c>1</c>.</p> - <p>As from Erlang/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 Erlang/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 Erlang/OTP R11B-4 can decode resulting - binary.</p> + The valid values for <c><anno>Version</anno></c> are:</p> + <taglist> + <tag><c>0</c></tag> + <item> + <p>Floats are encoded using a textual representation. + This option is useful to ensure that releases before Erlang/OTP + R11B-4 can decode resulting binary.</p> + <p>This version encode atoms that can be represented by a + latin1 string using latin1 encoding while only atoms that + cannot be represented by latin1 are encoded using utf8.</p> + </item> + <tag><c>1</c></tag> + <item> + <p>This is as of Erlang/OTP 17.0 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). As from Erlang/OTP R11B-4, + <c>binary_to_term/1</c> can decode this representation.</p> + <p>This version encode atoms that can be represented by a + latin1 string using latin1 encoding while only atoms that + cannot be represented by latin1 are encoded using utf8.</p> + </item> + <tag><c>2</c></tag> + <item> + <p>Drops usage of the latin1 atom encoding and unconditionally + use utf8 encoding for all atoms. This will be changed to the + default in a future major release of Erlang/OTP. Erlang/OTP + systems as of R16B can decode this representation.</p> + </item> + </taglist> <p>See also <seealso marker="#binary_to_term/1"> <c>binary_to_term/1</c></seealso>.</p> </desc> </func> <func> - <name name="throw" arity="1"/> + <name name="throw" arity="1" since=""/> <fsummary>Throw an exception.</fsummary> <desc> <p>A non-local return from a function. If evaluated within a @@ -8703,7 +9514,7 @@ hello </func> <func> - <name name="time" arity="0"/> + <name name="time" arity="0" since=""/> <fsummary>Current time.</fsummary> <desc> <p>Returns the current time as <c>{Hour, Minute, Second}</c>.</p> @@ -8716,7 +9527,7 @@ hello </func> <func> - <name name="time_offset" arity="0"/> + <name name="time_offset" arity="0" since="OTP 18.0"/> <fsummary>Current time offset.</fsummary> <desc> <p>Returns the current time offset between @@ -8748,7 +9559,7 @@ hello </func> <func> - <name name="time_offset" arity="1"/> + <name name="time_offset" arity="1" since="OTP 18.0"/> <fsummary>Current time offset.</fsummary> <desc> <p>Returns the current time offset between @@ -8767,7 +9578,7 @@ hello </func> <func> - <name name="timestamp" arity="0"/> + <name name="timestamp" arity="0" since="OTP 18.0"/> <fsummary>Current Erlang System time.</fsummary> <type name="timestamp"/> <desc> @@ -8806,7 +9617,7 @@ timestamp() -> </func> <func> - <name name="tl" arity="1"/> + <name name="tl" arity="1" since=""/> <fsummary>Tail of a list.</fsummary> <desc> <p>Returns the tail of <c><anno>List</anno></c>, that is, @@ -8821,7 +9632,7 @@ timestamp() -> </func> <func> - <name name="trace" arity="3"/> + <name name="trace" arity="3" since=""/> <fsummary>Set trace flags for a process or processes.</fsummary> <type name="trace_flag"/> <desc> @@ -9477,7 +10288,7 @@ timestamp() -> </func> <func> - <name name="trace_delivered" arity="1"/> + <name name="trace_delivered" arity="1" since=""/> <fsummary>Notification when trace has been delivered.</fsummary> <desc> <p>The delivery of trace messages (generated by @@ -9532,7 +10343,7 @@ timestamp() -> </func> <func> - <name name="trace_info" arity="2"/> + <name name="trace_info" arity="2" since=""/> <fsummary>Trace information about a process or function.</fsummary> <type name="trace_info_return"/> <type name="trace_info_item_result"/> @@ -9668,7 +10479,7 @@ timestamp() -> </func> <func> - <name name="trace_pattern" arity="2" clause_i="1"/> + <name name="trace_pattern" arity="2" clause_i="1" since=""/> <fsummary>Set trace patterns for call, send, or 'receive' tracing. </fsummary> <type name="trace_pattern_mfa"/> @@ -9686,7 +10497,7 @@ timestamp() -> </func> <func> - <name name="trace_pattern" arity="3" clause_i="1"/> + <name name="trace_pattern" arity="3" clause_i="1" since="?"/> <fsummary>Set trace pattern for message sending.</fsummary> <type name="trace_match_spec"/> <type name="match_variable"/> @@ -9757,7 +10568,7 @@ timestamp() -> </func> <func> - <name name="trace_pattern" arity="3" clause_i="2"/> + <name name="trace_pattern" arity="3" clause_i="2" since="?"/> <fsummary>Set trace pattern for tracing of message receiving.</fsummary> <type name="trace_match_spec"/> <type name="match_variable"/> @@ -9829,7 +10640,7 @@ timestamp() -> </func> <func> - <name name="trace_pattern" arity="3" clause_i="3"/> + <name name="trace_pattern" arity="3" clause_i="3" since=""/> <fsummary>Set trace patterns for tracing of function calls.</fsummary> <type name="trace_pattern_mfa"/> <type name="trace_match_spec"/> @@ -10020,7 +10831,7 @@ timestamp() -> </func> <func> - <name name="trunc" arity="1"/> + <name name="trunc" arity="1" since=""/> <fsummary>Return an integer by truncating a number.</fsummary> <desc> <p>Returns an integer by truncating <c><anno>Number</anno></c>, @@ -10033,7 +10844,7 @@ timestamp() -> </func> <func> - <name name="tuple_size" arity="1"/> + <name name="tuple_size" arity="1" since=""/> <fsummary>Return the size of a tuple.</fsummary> <desc> <p>Returns an integer that is the number of elements in @@ -10046,7 +10857,7 @@ timestamp() -> </func> <func> - <name name="tuple_to_list" arity="1"/> + <name name="tuple_to_list" arity="1" since=""/> <fsummary>Convert a tuple to a list.</fsummary> <desc> <p>Returns a list corresponding to <c><anno>Tuple</anno></c>. @@ -10059,7 +10870,7 @@ timestamp() -> </func> <func> - <name name="unique_integer" arity="0"/> + <name name="unique_integer" arity="0" since="OTP 18.0"/> <fsummary>Get a unique integer value.</fsummary> <desc> <p>Generates and returns an @@ -10072,7 +10883,7 @@ timestamp() -> </func> <func> - <name name="unique_integer" arity="1"/> + <name name="unique_integer" arity="1" since="OTP 18.0"/> <fsummary>Get a unique integer value.</fsummary> <desc> <p>Generates and returns an @@ -10154,7 +10965,7 @@ timestamp() -> </func> <func> - <name name="universaltime" arity="0"/> + <name name="universaltime" arity="0" since=""/> <fsummary>Current date and time according to Universal Time Coordinated (UTC).</fsummary> <desc> @@ -10171,7 +10982,7 @@ timestamp() -> </func> <func> - <name name="universaltime_to_localtime" arity="1"/> + <name name="universaltime_to_localtime" arity="1" since=""/> <fsummary>Convert from Universal Time Coordinated (UTC) to local date and time.</fsummary> <desc> @@ -10190,7 +11001,7 @@ timestamp() -> </func> <func> - <name name="unlink" arity="1"/> + <name name="unlink" arity="1" since=""/> <fsummary>Remove a link to another process or port.</fsummary> <desc> <p>Removes the link, if there is one, between the calling @@ -10236,7 +11047,7 @@ end</code> </func> <func> - <name name="unregister" arity="1"/> + <name name="unregister" arity="1" since=""/> <fsummary>Remove the registered name for a process (or port).</fsummary> <desc> <p>Removes the registered name <c><anno>RegName</anno></c> @@ -10252,7 +11063,7 @@ true</pre> </func> <func> - <name name="whereis" arity="1"/> + <name name="whereis" arity="1" since=""/> <fsummary>Get the pid (or port) with a specified registered name. </fsummary> <desc> @@ -10266,7 +11077,7 @@ true</pre> </func> <func> - <name name="yield" arity="0"/> + <name name="yield" arity="0" since=""/> <fsummary>Let other processes get a chance to execute.</fsummary> <desc> <p>Voluntarily lets other processes (if any) get a chance to @@ -10274,9 +11085,9 @@ true</pre> <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 have a - chance to run in another scheduler thread anyway. + <p>There is seldom or never any need to use this BIF + 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> @@ -10284,4 +11095,3 @@ true</pre> </func> </funcs> </erlref> - diff --git a/erts/doc/src/erlc.xml b/erts/doc/src/erlc.xml index 7355be488b..be9b4e8d97 100644 --- a/erts/doc/src/erlc.xml +++ b/erts/doc/src/erlc.xml @@ -4,7 +4,7 @@ <comref> <header> <copyright> - <year>1997</year><year>2016</year> + <year>1997</year><year>2018</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -143,6 +143,14 @@ <p>Produces a Makefile rule to track header dependencies. The rule is sent to <c>stdout</c>. No object file is produced.</p> </item> + + <tag><c>-MMD</c></tag> + <item> + <p>Generate dependencies as a side-effect. The object file + will be produced as normal. This option overrides the + option <c><![CDATA[-M]]></c>.</p> + </item> + <tag><c>-MF <Makefile></c></tag> <item> <p>As option <c><![CDATA[-M]]></c>, except that the diff --git a/erts/doc/src/erts_alloc.xml b/erts/doc/src/erts_alloc.xml index 8ab35851c1..a094217959 100644 --- a/erts/doc/src/erts_alloc.xml +++ b/erts/doc/src/erts_alloc.xml @@ -4,7 +4,7 @@ <cref> <header> <copyright> - <year>2002</year><year>2016</year> + <year>2002</year><year>2018</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -68,8 +68,7 @@ fixed size data types.</item> <tag><c>exec_alloc</c></tag> <item>Allocator used by the <seealso marker="hipe:HiPE_app"><c>HiPE</c></seealso> - application for native executable code on specific architectures - (x86_64).</item> + application for native executable code.</item> <tag><c>std_alloc</c></tag> <item>Allocator used for most memory blocks not allocated through any of the other allocators described above.</item> @@ -87,9 +86,9 @@ the number of system calls made.</item> </taglist> - <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 + <p><c>sys_alloc</c>, <c>literal_alloc</c> and <c>temp_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. @@ -225,6 +224,33 @@ used. The time complexity is proportional to log N, where N is the number of free blocks.</p> </item> + <tag>Age order first fit carrier address order first fit</tag> + <item> + <p>Strategy: Find the <em>oldest carrier</em> that + can satisfy the requested block size, then find a block within + that carrier using the "address order first fit" strategy.</p> + <p>Implementation: A balanced binary search tree is + used. The time complexity is proportional to log N, where + N is the number of free blocks.</p> + </item> + <tag>Age order first fit carrier best fit</tag> + <item> + <p>Strategy: Find the <em>oldest carrier</em> 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>Age order first fit carrier address order best fit</tag> + <item> + <p>Strategy: Find the <em>oldest carrier</em> that + can satisfy the requested block size, then find a block within + that carrier using the "address order 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>Good fit</tag> <item> <p>Strategy: Try to find the best fit, but settle for the best fit @@ -452,7 +478,7 @@ utilization value > 0 is used, allocator instances 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 is used. The value + a recommended non-zero utilization value is used. The value chosen depends on the allocator type and can be changed between ERTS versions. Defaults to <c>de</c>, but this can be changed in the future.</p> @@ -467,7 +493,8 @@ fetched, it will function as an ordinary carrier. This feature has special requirements on the <seealso marker="#M_as">allocation strategy</seealso> used. Only - the strategies <c>aoff</c>, <c>aoffcbf</c>, and <c>aoffcaobf</c> + the strategies <c>aoff</c>, <c>aoffcbf</c>, <c>aoffcaobf</c>, + <c>ageffcaoff</c>m, <c>ageffcbf</c> and <c>ageffcaobf</c> support abandoned carriers.</p> <p>This feature also requires <seealso marker="#M_t">multiple thread specific instances</seealso> @@ -478,8 +505,30 @@ allocators based on the <c>alloc_util</c> framework, except <c>temp_alloc</c> (which would be pointless).</p> </item> + + <tag><marker id="M_acfml"/><c><![CDATA[+M<S>acfml <bytes>]]></c> + </tag> + <item> + <p>Abandon carrier free block min limit. A valid <c><![CDATA[<bytes>]]></c> + is a positive integer representing a block size limit. The largest + free block in a carrier must be at least <c>bytes</c> large, for the + carrier to be abandoned. The default is zero but can be changed + in the future.</p> + <p>See also <seealso marker="#M_acul"><c>acul</c></seealso>.</p> + </item> + + <tag><marker id="M_acnl"/><c><![CDATA[+M<S>acnl <amount>]]></c> + </tag> + <item> + <p>Abandon carrier number limit. A valid <c><![CDATA[<amount>]]></c> + is a positive integer representing max number of abandoned carriers per + allocator instance. Defaults to 1000 which will practically disable + the limit, but this can be changed in the future.</p> + <p>See also <seealso marker="#M_acul"><c>acul</c></seealso>.</p> + </item> + <tag><marker id="M_as"/> - <c><![CDATA[+M<S>as bf|aobf|aoff|aoffcbf|aoffcaobf|gf|af]]></c></tag> + <c><![CDATA[+M<S>as bf|aobf|aoff|aoffcbf|aoffcaobf|ageffcaoff|ageffcbf|ageffcaobf|gf|af]]></c></tag> <item> <p>Allocation strategy. The following strategies are valid:</p> <list type="bulleted"> @@ -490,6 +539,11 @@ </item> <item><c>aoffcaobf</c> (address order first fit carrier address order best fit)</item> + <item><c>ageffcaoff</c> (age order first fit carrier address order first fit)</item> + <item><c>ageffcbf</c> (age order first fit carrier best fit) + </item> + <item><c>ageffcaobf</c> (age order first fit carrier address + order best fit)</item> <item><c>gf</c> (good fit)</item> <item><c>af</c> (a fit)</item> </list> @@ -505,6 +559,20 @@ than this threshold, otherwise the carrier is shrunk. See also <seealso marker="#M_rsbcst"><c>rsbcst</c></seealso>.</p> </item> + <tag><marker id="M_atags"/><c><![CDATA[+M<S>atags true|false]]></c></tag> + <item> + <p>Adds a small tag to each allocated block that contains basic + information about what it is and who allocated it. Use the + <seealso marker="tools:instrument"><c>instrument</c></seealso> + module to inspect this information.</p> + + <p>The runtime overhead is one word per allocation when enabled. This + may change at any time in the future.</p> + + <p>The default is <c>true</c> for <c>binary_alloc</c> and + <c>driver_alloc</c>, and <c>false</c> for the other allocator + types.</p> + </item> <tag><marker id="M_e"/><c><![CDATA[+M<S>e true|false]]></c></tag> <item> <p>Enables allocator <c><![CDATA[<S>]]></c>.</p> @@ -595,7 +663,7 @@ </item> <tag><marker id="M_sbct"/><c><![CDATA[+M<S>sbct <size>]]></c></tag> <item> - <p>Singleblock carrier threshold. Blocks larger than this + <p>Singleblock carrier threshold (in kilobytes). Blocks larger than this threshold are placed in singleblock carriers. Blocks smaller than this threshold are placed in multiblock carriers. On 32-bit Unix style OS this threshold cannot be set @@ -668,37 +736,14 @@ </section> <section> - <title>Special Flag for exec_alloc</title> - <taglist> - <tag><marker id="MXscs"/><c><![CDATA[+MXscs <size in MB>]]></c></tag> - <item> - <p><c>exec_alloc</c> super carrier size (in MB). The amount of - <em>virtual</em> address space reserved for native executable code - used by the <seealso marker="hipe:HiPE_app"><c>HiPE</c></seealso> application - on specific architectures (x86_64). Defaults to <c>512</c>.</p> - </item> - </taglist> - </section> - - <section> <title>Instrumentation Flags</title> <taglist> - <tag><marker id="Mim"/><c>+Mim true|false</c></tag> - <item> - <p>A map over current allocations is kept by the emulator. - The allocation map can be retrieved through module - <seealso marker="tools:instrument"> - <c>instrument(3)</c></seealso>. <c>+Mim true</c> - implies <c>+Mis true</c>. <c>+Mim true</c> is the same as flag - <seealso marker="erl#instr"><c>-instr</c></seealso> in - <c>erl(1)</c>.</p> - </item> - <tag><marker id="Mis"/><c>+Mis true|false</c></tag> - <item> - <p>Status over allocated memory is kept by the emulator. - The allocation status can be retrieved through module - <seealso marker="tools:instrument"> - <c>instrument(3)</c></seealso>.</p> + <tag><c>+M<S>atags</c></tag> + <item> + <p>Adds a small tag to each allocated block that contains basic + information about what it is and who allocated it. See + <seealso marker="#M_atags"><c>+M<S>atags</c></seealso> for a + more complete description.</p> </item> <tag><marker id="Mit"/><c>+Mit X</c></tag> <item> diff --git a/erts/doc/src/escript.xml b/erts/doc/src/escript.xml index 1d5d280338..be1664b39f 100644 --- a/erts/doc/src/escript.xml +++ b/erts/doc/src/escript.xml @@ -4,7 +4,7 @@ <comref> <header> <copyright> - <year>2007</year><year>2016</year> + <year>2007</year><year>2018</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -35,6 +35,28 @@ <p><c>escript</c> provides support for running short Erlang programs without having to compile them first, and an easy way to retrieve the command-line arguments.</p> + + <p>It is possible to bundle <c>escript</c>(s) with an Erlang + runtime system to make it self-sufficient and relocatable. In such + a standalone system, the <c>escript</c>(s) should be located in + the top <c>bin</c> directory of the standalone system and given + <c>.escript</c> as file extension. Further the (built-in) + <c>escript</c> program should be copied to the same directory and + given the scripts original name (without the <c>.escript</c> + extension). This will enable use of the bundled Erlang runtime + system.</p> + + <p>The (built-in) <c>escript</c> program first determines which + Erlang runtime system to use and then starts it to execute your + script. Usually the runtime system is located in the same Erlang + installation as the <c>escript</c> program itself. But for + standalone systems with one or more escripts it may be the case + that the <c>escript</c> program in your path actually starts the + runtime system bundled with the escript. This is intentional, and + typically happens when the standalone system <c>bin</c> directory is not + in the execution path (as it may cause its <c>erl</c> program to + override the desired one) and the <c>escript</c>(s) are referred to via + symbolic links from a <c>bin</c> directory in the path.</p> </description> <funcs> @@ -133,9 +155,12 @@ io:setopts([{encoding, unicode}])</code> for example:</p> <pre> halt(1).</pre> - <p>To retrieve the pathname of the script, call - <seealso marker="#script_name_0"> - <c>escript:script_name()</c></seealso> from your script + <p> + To retrieve the pathname of the script, call + <seealso marker="#script_name-0"> + <c>escript:script_name()</c> + </seealso> + from your script (the pathname is usually, but not always, absolute).</p> <p>If the file contains source code (as in the example above), it is processed by the @@ -207,6 +232,7 @@ $ <input>escript factorial.beam 5</input> factorial 5 = 120 $ <input>escript factorial.zip 5</input> factorial 5 = 120</pre> + <marker id="create-2"/> </desc> </func> @@ -237,7 +263,7 @@ factorial 5 = 120</pre> zip:create_option()</seealso>]</v> </type> <desc> - <p><marker id="create_2"></marker> + <p> Creates an escript from a list of sections. The sections can be specified in any order. An escript begins with an optional <c>Header</c> followed by a mandatory <c>Body</c>. If @@ -322,6 +348,7 @@ ok {{2010,3,2},{0,59,22}}, 54,1,0,0,0,0,0}, <<"%% demo.erl\n-module(demo).\n-export([main/1]).\n\n%% Demo\nmain(_Arg"...>>}]}</pre> + <marker id="extract-2"/> </desc> </func> @@ -346,9 +373,11 @@ ok <v>SourceCode = BeamCode = ZipArchive = binary()</v> </type> <desc> - <p><marker id="extract_2"></marker> - Parses an escript and extracts its sections. This is the reverse - of <seealso marker="#create_2"><c>create/2</c></seealso>.</p> + <p> + Parses an escript and extracts its sections. + This is the reverse of + <seealso marker="#create-2"><c>create/2</c></seealso>. + </p> <p>All sections are returned even if they do not exist in the escript. If a particular section happens to have the same value as the default value, the extracted value is set to the @@ -371,6 +400,7 @@ ok {ok,[{{archive,<<80,75,3,4,20,0,0,0,8,0,118,7,98,60,105, 152,61,93,107,0,0,0,118,0,...>>} {emu_args,undefined}]}</pre> + <marker id="script_name-0"/> </desc> </func> @@ -381,7 +411,7 @@ ok <v>File = filename()</v> </type> <desc> - <p><marker id="script_name_0"></marker> + <p> Returns the name of the escript that is executed. If the function is invoked outside the context of an escript, the behavior is undefined.</p> diff --git a/erts/doc/src/fascicules.xml b/erts/doc/src/fascicules.xml deleted file mode 100644 index 1c371bd9c8..0000000000 --- a/erts/doc/src/fascicules.xml +++ /dev/null @@ -1,18 +0,0 @@ -<?xml version="1.0" encoding="utf-8" ?> -<!DOCTYPE fascicules SYSTEM "fascicules.dtd"> - -<fascicules> - <fascicule file="part" href="part_frame.html" entry="no"> - ERTS User's Guide - </fascicule> - <fascicule file="ref_man" href="ref_man_frame.html" entry="yes"> - ERTS Reference Manual - </fascicule> - <fascicule file="part_notes" href="part_notes_frame.html" entry="no"> - Release Notes - </fascicule> - <fascicule file="" href="../../../doc/print.html" entry="no"> - Off-Print - </fascicule> -</fascicules> - diff --git a/erts/doc/src/init.xml b/erts/doc/src/init.xml index c14f0a558d..c824e37976 100644 --- a/erts/doc/src/init.xml +++ b/erts/doc/src/init.xml @@ -29,7 +29,7 @@ <rev></rev> <file>init.xml</file> </header> - <module>init</module> + <module since="">init</module> <modulesummary>Coordination of system startup.</modulesummary> <description> <p>This module is preloaded and contains the code for @@ -50,7 +50,7 @@ <funcs> <func> - <name name="boot" arity="1"/> + <name name="boot" arity="1" since=""/> <fsummary>Start the Erlang runtime system.</fsummary> <desc> <p>Starts the Erlang runtime system. This function is called @@ -69,7 +69,7 @@ </func> <func> - <name name="get_argument" arity="1"/> + <name name="get_argument" arity="1" since=""/> <fsummary>Get the values associated with a command-line user flag. </fsummary> <desc> @@ -112,7 +112,7 @@ </func> <func> - <name name="get_arguments" arity="0"/> + <name name="get_arguments" arity="0" since=""/> <fsummary>Get all command-line user flags.</fsummary> <desc> <p>Returns all command-line flags and the system-defined flags, see @@ -121,7 +121,7 @@ </func> <func> - <name name="get_plain_arguments" arity="0"/> + <name name="get_plain_arguments" arity="0" since=""/> <fsummary>Get all non-flag command-line arguments.</fsummary> <desc> <p>Returns any plain command-line arguments as a list of strings @@ -130,7 +130,7 @@ </func> <func> - <name name="get_status" arity="0"/> + <name name="get_status" arity="0" since=""/> <fsummary>Get system status information.</fsummary> <type name="internal_status"/> <desc> @@ -146,7 +146,7 @@ </func> <func> - <name name="reboot" arity="0"/> + <name name="reboot" arity="0" since=""/> <fsummary>Take down and restart an Erlang node smoothly.</fsummary> <desc> <p>All applications are taken down smoothly, all code is @@ -162,7 +162,7 @@ </func> <func> - <name name="restart" arity="0"/> + <name name="restart" arity="0" since=""/> <fsummary>Restart the running Erlang node.</fsummary> <desc> <p>The system is restarted <em>inside</em> the running Erlang @@ -178,7 +178,7 @@ </func> <func> - <name name="script_id" arity="0"/> + <name name="script_id" arity="0" since=""/> <fsummary>Get the identity of the used boot script.</fsummary> <desc> <p>Gets the identity of the boot script used to boot the system. @@ -189,7 +189,7 @@ </func> <func> - <name name="stop" arity="0"/> + <name name="stop" arity="0" since=""/> <fsummary>Take down an Erlang node smoothly.</fsummary> <desc> <p>The same as @@ -198,7 +198,7 @@ </func> <func> - <name name="stop" arity="1"/> + <name name="stop" arity="1" since=""/> <fsummary>Take down an Erlang node smoothly.</fsummary> <desc> <p>All applications are taken down smoothly, all code is diff --git a/erts/doc/src/match_spec.xml b/erts/doc/src/match_spec.xml index 2a14f1e47b..48e502739a 100644 --- a/erts/doc/src/match_spec.xml +++ b/erts/doc/src/match_spec.xml @@ -4,7 +4,7 @@ <chapter> <header> <copyright> - <year>1999</year><year>2016</year> + <year>1999</year><year>2018</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -86,12 +86,12 @@ <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> + <c><![CDATA[is_map]]></c> | <c><![CDATA[is_map_key]]></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 @@ -110,8 +110,10 @@ </item> <item>GuardFunction ::= BoolFunction | <c><![CDATA[abs]]></c> | <c><![CDATA[element]]></c> | <c><![CDATA[hd]]></c> | - <c><![CDATA[length]]></c> | <c><![CDATA[node]]></c> | + <c><![CDATA[length]]></c> | <c><![CDATA[map_get]]></c> | + <c><![CDATA[map_size]]></c> | <c><![CDATA[node]]></c> | <c><![CDATA[round]]></c> | <c><![CDATA[size]]></c> | + <c><![CDATA[bit_size]]></c> | <c><![CDATA[tl]]></c> | <c><![CDATA[trunc]]></c> | <c><![CDATA['+']]></c> | <c><![CDATA['-']]></c> | <c><![CDATA['*']]></c> | <c><![CDATA['div']]></c> | @@ -167,9 +169,9 @@ <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[is_map]]></c> | <c><![CDATA[map_is_key]]></c> | + <c><![CDATA[is_binary]]></c> | <c><![CDATA[is_function]]></c> | + <c><![CDATA[is_record]]></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> @@ -190,8 +192,10 @@ </item> <item>GuardFunction ::= BoolFunction | <c><![CDATA[abs]]></c> | <c><![CDATA[element]]></c> | <c><![CDATA[hd]]></c> | - <c><![CDATA[length]]></c> | <c><![CDATA[node]]></c> | + <c><![CDATA[length]]></c> | <c><![CDATA[map_get]]></c> | + <c><![CDATA[map_size]]></c> | <c><![CDATA[node]]></c> | <c><![CDATA[round]]></c> | <c><![CDATA[size]]></c> | + <c><![CDATA[bit_size]]></c> | <c><![CDATA[tl]]></c> | <c><![CDATA[trunc]]></c> | <c><![CDATA['+']]></c> | <c><![CDATA['-']]></c> | <c><![CDATA['*']]></c> | <c><![CDATA['div']]></c> | @@ -202,8 +206,7 @@ <c><![CDATA['>=']]></c> | <c><![CDATA['<']]></c> | <c><![CDATA['=<']]></c> | <c><![CDATA['=:=']]></c> | <c><![CDATA['==']]></c> | <c><![CDATA['=/=']]></c> | - <c><![CDATA['/=']]></c> | <c><![CDATA[self]]></c> | - <c><![CDATA[get_tcw]]></c> + <c><![CDATA['/=']]></c> | <c><![CDATA[self]]></c> </item> <item>MatchBody ::= [ ConditionExpression, ... ] </item> @@ -268,8 +271,9 @@ other <c>false</c> to return <c><![CDATA[true]]></c>; otherwise <c><![CDATA['xor']]></c> returns false.</p> </item> - <tag><c>abs</c>, <c>element</c>, <c>hd</c>, <c>length</c>, <c>node</c>, - <c>round</c>, <c>size</c>, <c>tl</c>, <c>trunc</c>, <c>'+'</c>, + <tag><c>abs</c>, <c>element</c>, <c>hd</c>, <c>length</c>, + <c>map_get</c>, <c>map_size</c>, <c>node</c>, <c>round</c>, + <c>size</c>, <c>bit_size</c>, <c>tl</c>, <c>trunc</c>, <c>'+'</c>, <c>'-'</c>, <c>'*'</c>, <c>'div'</c>, <c>'rem'</c>, <c>'band'</c>, <c>'bor'</c>, <c>'bxor'</c>, <c>'bnot'</c>, <c>'bsl'</c>, <c>'bsr'</c>, <c>'>'</c>, <c>'>='</c>, <c>'<'</c>, <c>'=<'</c>, @@ -405,7 +409,8 @@ <c><![CDATA[tracer]]></c>.</p> <p>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 specification is used.</p> + tracer as the process executing the match specification is used (not the meta tracer). + If that process doesn't have tracer either, then trace flags are ignored.</p> <p>When using a <seealso marker="erl_tracer">tracer module</seealso>, the module must be loaded before the match specification is executed. If it is not loaded, the match fails.</p> @@ -866,4 +871,3 @@ can be useful for testing complicated ETS matches.</p> </section> </chapter> - diff --git a/erts/doc/src/notes.xml b/erts/doc/src/notes.xml index 972ca63272..e4ff9b45c9 100644 --- a/erts/doc/src/notes.xml +++ b/erts/doc/src/notes.xml @@ -4,7 +4,7 @@ <chapter> <header> <copyright> - <year>2004</year><year>2017</year> + <year>2004</year><year>2018</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -31,6 +31,3195 @@ </header> <p>This document describes the changes made to the ERTS application.</p> +<section><title>Erts 10.2.1</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> + Fixed bug on big endian architectures when changing file + permissions or ownership with <c>file:change_mode</c>, + <c>change_owner</c>, <c>change_group</c> or + <c>write_file_info</c>. Bug exists since OTP-21.0.</p> + <p> + Own Id: OTP-15485</p> + </item> + <item> + <p> + Fixed bug in <c>atomics</c> with option + <c>{signed,false}</c> when returned values are <c>(1 bsl + 63)</c> or larger. Could cause heap corruption leading to + VM crash or other unpleasant symptoms. Bug exists since + OTP-21.2 when module <c>atomics</c> was introduced.</p> + <p> + Own Id: OTP-15486 Aux Id: PR-2061 </p> + </item> + <item> + <p> + Fixed bug in operator <c>band</c> of two negative + operands causing erroneous result if the absolute value + of one of the operands have the lowest <c>N*W</c> bits as + zero and the other absolute value is not larger than + <c>N*W</c> bits. <c>N</c> is an integer of 1 or larger + and <c>W</c> is 32 or 64 depending on word size.</p> + <p> + Own Id: OTP-15487 Aux Id: ERL-804 </p> + </item> + </list> + </section> + +</section> + +<section><title>Erts 10.2</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> + When a process was waiting for a TCP socket send + operation to complete, and another process closed the + socket during that send, the sending process could hang. + This bug has now been corrected.</p> + <p> + Own Id: OTP-12242 Aux Id: ERL-561 </p> + </item> + <item> + <p> + Document <c>bit_size</c> in match specifications and + allow it in <c>ets:fun2ms</c>.</p> + <p> + Own Id: OTP-15343 Aux Id: PR-1962 </p> + </item> + <item> + <p> + Fixed bug in <c>ets:select_replace</c> when called with a + fully bound key could cause a following call to + <c>ets:next</c> or <c>ets:prev</c> to crash the emulator + or return invalid result.</p> + <p> + Own Id: OTP-15346</p> + </item> + <item> + <p>When a module has been purged from memory, any + literals belonging to that module will be copied to all + processes that hold references to them. The max heap size + limit would be ignored in the garbage collection + initiated when copying literals to a process. If the max + heap size was exceeded, the process would typically be + terminated in the following garbage collection. Corrected + to terminate the process directly if copying a literal + would exceed the max heap size.</p> + <p> + Own Id: OTP-15360</p> + </item> + <item> + <p> + Fix compilation of run_erl on Solaris 11.4 and later.</p> + <p> + Own Id: OTP-15389</p> + </item> + <item> + <p>Fixed a bug where <c>lists:reverse/1-2</c> could use + far too many reductions. This bug was introduced in + <c>OTP 21.1</c>.</p> + <p> + Own Id: OTP-15436</p> + </item> + <item> + <p>Fixed a bug where a dirty scheduler could stay awake + forever if a distribution entry was removed as part of a + dirty GC.</p> + <p> + Own Id: OTP-15446 Aux Id: PR-2024 </p> + </item> + <item> + <p> + Fix microstate accounting handing in various places. Most + importantly the GC states when the GC is run on a dirty + scheduler are now managed correctly.</p> + <p> + Own Id: OTP-15450 Aux Id: ERIERL-229 </p> + </item> + <item> + <p> + Fixed bug in <c>file:sendfile</c> when the send operation + failed. For sockets in <c>active</c> modes it could cause + emulator crash or a hanging call. For sockets with + <c>{active,false}</c> an unexpected <c>{inet_reply, _, + _}</c> message could be sent to the calling process. The + bug exists since OTP-21.0.</p> + <p> + Own Id: OTP-15461 Aux Id: ERL-784 </p> + </item> + <item> + <p> + The erts configure script has been updated to reject any + CFLAGS that does not have <c>-O</c>. This in order to + prevent the common mistake of forgetting to add + <c>-O2</c> to custom CFLAGS.</p> + <p> + Own Id: OTP-15465</p> + </item> + <item> + <p> + Fix reduction count in lists:member/2</p> + <p> + Own Id: OTP-15474 Aux Id: ERIERL-229 </p> + </item> + </list> + </section> + + + <section><title>Improvements and New Features</title> + <list> + <item> + <p> + New <c>counters</c> and <c>atomics</c> modules supplies + access to highly efficient operations on mutable fixed + word sized variables.</p> + <p> + Own Id: OTP-13468</p> + </item> + <item> + <p>There is a new module <c>persistent_term</c> that + implements a term storage suitable for terms that are + frequently used but never or infrequently updated. + Lookups are done in constant time without copying the + terms.</p> + <p> + Own Id: OTP-14669 Aux Id: PR-1989 </p> + </item> + <item> + <p> + A function <c>inet:getifaddrs/1</c> that takes a list + with a namespace option has been added, for platforms + that support that feature, for example Linux (only?).</p> + <p> + Own Id: OTP-15121 Aux Id: ERIERL-189, PR-1974 </p> + </item> + <item> + <p>Added the <c>nopush</c> option for TCP sockets, which + corresponds to <c>TCP_NOPUSH</c> on *BSD and + <c>TCP_CORK</c> on Linux.</p> + <p>This is also used internally in <c>file:sendfile</c> + to reduce latency on subsequent send operations.</p> + <p> + Own Id: OTP-15357 Aux Id: ERL-698 </p> + </item> + <item> + <p>List subtraction (The <c>--</c> operator) will now + yield properly on large inputs.</p> + <p> + Own Id: OTP-15371</p> + </item> + <item> + <p> + Optimize handling of send_delay for tcp sockes to better + work with the new pollthread implementation introduced in + OTP-21.</p> + <p> + Own Id: OTP-15471 Aux Id: ERIERL-229 </p> + </item> + <item> + <p> + Optimize driver_set_timer with a zero timeout to + short-circuit and not create any timer structure, but + instead schedule the timer immediately.</p> + <p> + Own Id: OTP-15472 Aux Id: ERIERL-229 </p> + </item> + <item> + <p> + Add <c>erl_xcomp_code_model_small</c> as a cross + configure variable in order to let the emulator be build + with the assumption that a small code model will be used + on the target machine.</p> + <p> + Own Id: OTP-15473 Aux Id: ERIERL-229 </p> + </item> + <item> + <p> + Add a new pollset that is made to handle sockets that use + <c>{active, true}</c> or <c>{active, N}</c>. The new + pollset will not be polled by a pollthread, but instead + polled by a normal scheduler.</p> + <p> + This change was made because of the overhead associated + with constantly having to re-apply the ONESHOT mechanism + on fds that all input events were interesting.</p> + <p> + The new pollset is only active on platforms that support + concurrent kernel poll updates, i.e. Linux and BSD.</p> + <p> + Own Id: OTP-15475 Aux Id: ERIERL-229 </p> + </item> + <item> + <p> + Fix bug where emulator would segfault if a literal + message was sent when sequence tracing was enabled.</p> + <p> + Own Id: OTP-15478 Aux Id: ERL-741 </p> + </item> + </list> + </section> + +</section> + +<section><title>Erts 10.1.3</title> + + <section><title>Improvements and New Features</title> + <list> + <item> + <p>Added an optional <c>./configure</c> flag to compile + the emulator with spectre mitigation: + <c>--with-spectre-mitigation</c></p> + <p>Note that this requires a recent version of GCC with + support for spectre mitigation and the + <c>--mindirect-branch=thunk</c> flag, such as + <c>8.1</c>.</p> + <p> + Own Id: OTP-15430 Aux Id: ERIERL-237 </p> + </item> + </list> + </section> + +</section> + +<section><title>Erts 10.1.2</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p>Fixed a rare bug where files could be closed on a + normal instead of an IO scheduler, resulting in system + instability if the operation blocked.</p> + <p> + Own Id: OTP-15421</p> + </item> + </list> + </section> + +</section> + +<section><title>Erts 10.1.1</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> + A bug where the socket option 'pktoptions' caused a read + of uninitialized memory has been fixed. Would cause + malfunction on FreeBSD.</p> + <p> + Own Id: OTP-14297 Aux Id: OTP-15141 </p> + </item> + <item> + <p>Fixed a memory leak on errors when reading files.</p> + <p> + Own Id: OTP-15318</p> + </item> + <item> + <p>File access through UNC paths works again on Windows. + This regression was introduced in OTP 21.</p> + <p> + Own Id: OTP-15333 Aux Id: ERL-737 </p> + </item> + </list> + </section> + +</section> + +<section><title>Erts 10.1</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> + Fix the seq_trace token to not be cleared when a process + receives messages sent by erts. Some examples of when + this could happen is all port BIFs, i.e. + <c>open_port</c>, <c>port_command</c> etc etc.</p> + <p> + Fix so that messages sent by nifs can be traced using + normal and <c>seq_trace</c> tracing.</p> + <p> + Own Id: OTP-15038 Aux Id: ERL-602 </p> + </item> + <item> + <p> + Fixed specs and documentation for <c>process_info</c> + item <c>monitored_by</c> to include port identifiers and + nif resources as possible types.</p> + <p> + Own Id: OTP-15180 Aux Id: ERL-648 </p> + </item> + <item> + <p> + Fix bug in generation of erl_crash.dump, which could + cause VM to crash.</p> + <p> + Bug exist since erts-9.2 (OTP-20.2).</p> + <p> + Own Id: OTP-15181</p> + </item> + <item> + <p> + Fix bug where ctrl-break or ctrl-c would not trigger the + break mode properly on Windows. This bug was introduced + in erts-10.0 (OTP-21).</p> + <p> + Own Id: OTP-15205</p> + </item> + <item> + <p> + Fix a performance bug for reception of UDP packages, + where a memory buffer would be reallocated when it should + not have been.</p> + <p> + Introduce a limit on the maximum automatic increase of + the UDP user-space buffer to the theoretical max of the + network PATH, i.e. 65535.</p> + <p> + Own Id: OTP-15206</p> + </item> + <item> + <p> + Fix alignment of erts allocator state internally in erts. + With the improper alignment the emulator would refuse to + start when compiled with clang on 32-bit systems.</p> + <p> + Own Id: OTP-15208 Aux Id: PR-1897 ERL-677 </p> + </item> + <item> + <p> + Fix bug where too many concurrent calls to + <c>erlang:open_port({spawn,"cmd"},...)</c> would result + in the emulator terminating with the reason "Failed to + write to erl_child_setup: ". After this fix the + <c>open_port</c> call will throw an <c>emfile</c> + exception instead.</p> + <p> + Own Id: OTP-15210</p> + </item> + <item> + <p> + Upgraded the ERTS internal PCRE library from version 8.41 + to version 8.42. See <url + href="http://pcre.org/original/changelog.txt">http://pcre.org/original/changelog.txt</url> + for information about changes made to PCRE. This library + implements major parts of the <seealso + marker="stdlib:re"><c>re</c></seealso> regular + expressions module.</p> + <p> + Own Id: OTP-15217</p> + </item> + <item> + <p> + Fix <c>open_port({fd,X,Y}, ...)</c> to release the file + descriptors from the pollset when closing the port. + Without this fix the same file descriptor number could + not be reused when doing multiple open_port and + port_close sequences.</p> + <p> + Own Id: OTP-15236 Aux Id: ERL-692 </p> + </item> + <item> + <p> + Fixed bug in <c>float_to_list/2</c> and + <c>float_to_binary/2</c> with options + <c>[{decimals,0},compact]</c> causing totally wrong + results. Bug exists since OTP-21.0.</p> + <p> + Own Id: OTP-15276 Aux Id: PR-1920 </p> + </item> + <item> + <p> + Fixed bug in <c>erlang:memory</c> causing <c>ets</c> to + report too much. This small false memory leak (16 bytes + each time) can only happen when a specific race condition + occurs between scheduler threads on a table with option + <c>write_concurrency</c>.</p> + <p> + Own Id: OTP-15278</p> + </item> + <item> + <p> + Minor <c>configure</c> test fixes</p> + <p> + Own Id: OTP-15282</p> + </item> + <item> + <p> + Improved robustness of distribution connection setup. In + OTP-21.0 a truly asynchronous connection setup was + introduced. This is further improvement on that work to + make the emulator more robust and also be able to recover + in cases when involved Erlang processes misbehave.</p> + <p> + Own Id: OTP-15297 Aux Id: OTP-15279, OTP-15280 </p> + </item> + </list> + </section> + + + <section><title>Improvements and New Features</title> + <list> + <item> + <p> + The socket options <c>recvtos</c>, <c>recvttl</c>, + <c>recvtclass</c> and <c>pktoptions</c> have been + implemented in the socket modules. See the documentation + for the <c>gen_tcp</c>, <c>gen_udp</c> and <c>inet</c> + modules. Note that support for these in the runtime + system is platform dependent. Especially for + <c>pktoptions</c> which is very Linux specific and + obsoleted by the RFCs that defined it.</p> + <p> + Own Id: OTP-15145 Aux Id: ERIERL-187 </p> + </item> + </list> + </section> + +</section> + +<section><title>Erts 10.0.8</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> + As of ERTS version 10.0 (OTP 21.0) the + <c>erl_child_setup</c> program, which creates port + programs, ignores <c>TERM</c> signals. This setting was + unintentionally inherited by port programs. Handling of + <c>TERM</c> signals in port programs has now been + restored to the default behavior. That is, terminate the + process.</p> + <p> + Own Id: OTP-15289 Aux Id: ERIERL-235, OTP-14943, ERL-576 </p> + </item> + <item> + <p> + The fix made for OTP-15279 in erts-10.07 (OTP-21.0.8) was + not complete. It could cause a new connection attempt to + be incorrectly aborted in certain cases. This fix will + amend that flaw.</p> + <p> + Own Id: OTP-15296 Aux Id: OTP-15279, ERIERL-226 </p> + </item> + </list> + </section> + +</section> + +<section><title>Erts 10.0.7</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> + A process could get stuck in an infinite rescheduling + loop between normal and dirty schedulers. This bug was + introduced in ERTS version 10.0.</p> + <p> + Thanks to Maxim Fedorov for finding and fixing this + issue.</p> + <p> + Own Id: OTP-15275 Aux Id: PR-1943 </p> + </item> + <item> + <p> + Garbage collection of a distribution entry could cause an + emulator crash if <c>net_kernel</c> had not brought + previous connection attempts on it down properly.</p> + <p> + Own Id: OTP-15279 Aux Id: ERIERL-226 </p> + </item> + </list> + </section> + +</section> + +<section><title>Erts 10.0.6</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> + A race between termination of a process and resume of the + same process via <c>erlang:resume_process/1</c> could + cause the VM to crash. This bug was introduced in erts + version 10.0 (OTP 21.0).</p> + <p> + Own Id: OTP-15237</p> + </item> + <item> + <p> + When tracing on <c>running</c>, <c>in</c> trace events + could be lost when a process was rescheduled between a + dirty and a normal scheduler.</p> + <p> + Own Id: OTP-15269 Aux Id: ERL-713 </p> + </item> + </list> + </section> + +</section> + +<section><title>Erts 10.0.5</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> + Fixed a bug which caused an emulator crash when + <c>enif_send()</c> was called by a NIF that executed on a + dirty scheduler. The bug was either triggered when the + NIF called <c>enif_send()</c> without a message + environment, or when the process executing the NIF was + <c>send</c> traced.</p> + <p> + Own Id: OTP-15223</p> + </item> + <item> + <p> + Fixed a bug causing some Erlang references to be + inconsistently ordered. This could for example cause + failure to look up certain elements with references as + keys in search data structures. This bug was introduced + in R13B02.</p> + <p> + Thanks to Simon Cornish for finding the bug and supplying + a fix.</p> + <p> + *** POTENTIAL INCOMPATIBILITY ***</p> + <p> + Own Id: OTP-15225</p> + </item> + </list> + </section> + +</section> + +<section><title>Erts 10.0.4</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p>Fixed a bug that prevented the <c>noshell</c> option + from working correctly on Mac OS X and BSD.</p> + <p> + Own Id: OTP-15169</p> + </item> + <item> + <p>Fixed a crash when matching directly against a literal + map using a single key that had been saved on the + stack.</p> + <p> + Own Id: OTP-15184</p> + </item> + <item> + <p>Fix node crash when passing a bad time option to + <c>file:read_file_info/2</c>.</p> + <p> + Own Id: OTP-15196</p> + </item> + </list> + </section> + +</section> + +<section><title>Erts 10.0.3</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p>Fixed a scheduler bug that caused normal schedulers to + run dirty code.</p> + <p> + Own Id: OTP-15154</p> + </item> + <item> + <p> + Fixed a bug in <c>erlang:trace_info/2</c> which caused + the emulator to crash when a bad argument was passed. The + bug was introduced in ERTS version 10.0.</p> + <p> + Own Id: OTP-15183 Aux Id: ERL-670 </p> + </item> + </list> + </section> + +</section> + +<section><title>Erts 10.0.2</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p>Fixed a rare bug that could cause processes to be + scheduled after they had been freed.</p> + <p> + Own Id: OTP-15067 Aux Id: ERL-573 </p> + </item> + <item> + <p>Fixed a race condition in the inet driver that could + cause receive to hang when the emulator was compiled with + gcc 8.</p> + <p> + Own Id: OTP-15158 Aux Id: ERL-654 </p> + </item> + </list> + </section> + +</section> + +<section><title>Erts 10.0.1</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p>The keys used in <c>os:getenv</c> and <c>os:putenv</c> + are case-insensitive again on Windows.</p> + <p> + Own Id: OTP-15147 Aux Id: ERL-644 </p> + </item> + </list> + </section> + +</section> + +<section><title>Erts 10.0</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> + The type specifications for <c>file:posix/0</c> and + <c>inet:posix/0</c> have been updated according to which + errors file and socket operations should be able to + return.</p> + <p> + Own Id: OTP-14019 Aux Id: ERL-550 </p> + </item> + <item> + <p> + Fix error printout from run_erl and a bug that could + cause unintended fds to be leaked into the started + program.</p> + <p> + Own Id: OTP-14537 Aux Id: PR1529 </p> + </item> + <item> + <p> File operations used to accept <seealso + marker="kernel:file#type-name_all">filenames</seealso> + containing null characters (integer value zero). This + caused the name to be truncated and in some cases + arguments to primitive operations to be mixed up. + Filenames containing null characters inside the filename + are now <em>rejected</em> and will cause primitive file + operations to fail. </p> <p> Also environment variable + operations used to accept <seealso + marker="kernel:os#type-env_var_name">names</seealso> and + <seealso + marker="kernel:os#type-env_var_value">values</seealso> of + environment variables containing null characters (integer + value zero). This caused operations to silently produce + erroneous results. Environment variable names and values + containing null characters inside the name or value are + now <em>rejected</em> and will cause environment variable + operations to fail. </p> <p>Primitive environment + variable operations also used to accept the <c>$=</c> + character in environment variable names causing various + problems. <c>$=</c> characters in environment variable + names are now also <em>rejected</em>. </p> <p>Also + <seealso + marker="kernel:os#cmd/1"><c>os:cmd/1</c></seealso> now + reject null characters inside its <seealso + marker="kernel:os#type-os_command">command</seealso>. + </p> <p><seealso + marker="erts:erlang#open_port/2"><c>erlang:open_port/2</c></seealso> + will also reject null characters inside the port name + from now on.</p> + <p> + *** POTENTIAL INCOMPATIBILITY ***</p> + <p> + Own Id: OTP-14543 Aux Id: ERL-370 </p> + </item> + <item> + <p> + Fix bugs related to the bookkeeping of microstate + accounting states.</p> + <p> + Own Id: OTP-14652</p> + </item> + <item> + <p><c>os:putenv</c> and <c>os:getenv</c> no longer access + the process environment directly and instead work on a + thread-safe emulation. The only observable difference is + that it's <em>not</em> kept in sync with libc + <c>getenv(3)</c> / <c>putenv(3)</c>, so those who relied + on that behavior in drivers or NIFs will need to add + manual synchronization.</p> <p>On Windows this means that + you can no longer resolve DLL dependencies by modifying + the <c>PATH</c> just before loading the driver/NIF. To + make this less of a problem, the emulator now adds the + target DLL's folder to the DLL search path.</p> + <p> + *** POTENTIAL INCOMPATIBILITY ***</p> + <p> + Own Id: OTP-14666</p> + </item> + <item> + <p>Corrected <c>erlang:is_builtin(erlang, M, F)</c> to + return <c>true</c> for <c>apply/2</c> and + <c>yield/0</c>.</p> + <p> + Own Id: OTP-14713 Aux Id: ERL-500 </p> + </item> + <item> + <p>Fixed a bug where the PATH environment variable wasn't + updated correctly on a release downgrade, effectively + keeping the PATH of the new release.</p> + <p> + Own Id: OTP-14719</p> + </item> + <item> + <p>A receive optimization that avoids scanning the entire + message queue when receiving a message containing a + freshly created reference could in rare circumstances + (involving recursive calls to the functions that does the + receive) cause the receive to hang. This has been + corrected.</p> + <p> + Own Id: OTP-14782 Aux Id: ERL-511 </p> + </item> + <item> + <p> + Fix building of Erlang/OTP on platforms which have small + data area with short addressing. For example the + PowerPC/RTEMS platform.</p> + <p> + Own Id: OTP-14909 Aux Id: PR-1692 </p> + </item> + <item> + <p>Fixed a crash when <c>enif_make_binary</c> is called + with a binary produced by <c>enif_inspect_binary</c> in a + different environment.</p> + <p> + Own Id: OTP-14931</p> + </item> + <item> + <p>Fixed a crash when <c>enif_make_binary</c> is called + more than once with a binary that had previously been + added to an <c>enif_ioq</c>.</p> + <p> + Own Id: OTP-14932</p> + </item> + <item> + <p> + The erl_child_setup program now ignores SIGTERM signals.</p> + <p> + Own Id: OTP-14943 Aux Id: ERL-576 </p> + </item> + <item> + <p> + Force 64-bit alignment on pre-allocators on architectures + which needs it.</p> + <p> + Own Id: OTP-14977</p> + </item> + <item> + <p> + Fixed a bug where dirty scheduler picked up non-dirty + work.</p> + <p> + Own Id: OTP-14978</p> + </item> + <item> + <p> + Calls to <c>gen_tcp:send/2</c> on closed sockets now + returns <c>{error, closed}</c> instead of + <c>{error,enotconn}</c>.</p> + <p> + Own Id: OTP-15001</p> + </item> + <item> + <p> + <c>erlang:monotonic_time/1</c> failed with <c>badarg</c> + when passing the <c>perf_counter</c> time unit as + argument.</p> + <p> + Own Id: OTP-15008</p> + </item> + <item> + <p> + Fix bug where rapid <c>init:restart()</c> calls would + sometimes crash because a code load request leaked in + between the restarts.</p> + <p> + Own Id: OTP-15013</p> + </item> + <item> + <p> + Improve <c>float_to_list(F, [{decimals,D}])</c> to closer + conform with <c>io_lib:format("~.*f", [D,F])</c>.</p> + <p> + There are however, still cases when <c>float_to_list</c> + does not produce the exact same result as + <c>io_lib:format</c>, especially for large values + <c>F</c> and/or many decimals <c>D</c>.</p> + <p> + Own Id: OTP-15015 Aux Id: OTP-14890 </p> + </item> + <item> + <p>Fixed a deadlock that would occur on certain + allocators when a reallocation failed with <c>+ramv</c> + enabled.</p> + <p> + Own Id: OTP-15024</p> + </item> + <item> + <p> + Fix bug that made it impossible to use an erl_tracer as + the seq_trace trace receiver.</p> + <p> + Own Id: OTP-15029</p> + </item> + <item> + <p> + Fix bug where a large (> 1 GB) emulator generated error + logger message would cause the emulator to crash.</p> + <p> + Own Id: OTP-15032</p> + </item> + <item> + <p>The emulator will no longer crash when reading the + file information of an ordinary file that has an NTFS + reparse point, such as files stored in a OneDrive-mapped + folder.</p> + <p> + Own Id: OTP-15062 Aux Id: ERL-615 </p> + </item> + <item> + <p> + Fixed bug in <c>enif_binary_to_term</c> which could cause + memory corruption for immediate terms (atoms, small + integers, pids, ports, empty lists).</p> + <p> + Own Id: OTP-15080</p> + </item> + <item> + <p> + Fixed bug in <c>erlang:system_profile/2</c> that could + cause superfluous <c>{profile,_,active,_,_}</c> messages + for terminating processes.</p> + <p> + Own Id: OTP-15085</p> + </item> + <item> + <p> + On OSs with per thread CPU time support, change + <c>cpu_timestamp</c> in <seealso + marker="erlang#trace/3">erlang:trace/3</seealso> to use + it instead of per process CPU time. This makes this + option useable on such OSs when running multiple + schedulers.</p> + <p> + Own Id: OTP-15090</p> + </item> + <item> + <p> + Fix segfault in abort_signal_task which could happen if a + port terminated while there were outstanding port tasks + that were not signals, for example a + ready_input/ready_output event.</p> + <p> + Own Id: OTP-15108 Aux Id: ERL-621 </p> + </item> + <item> + <p> + Fixed bug in <c>ets</c> that could cause VM crash if + process A terminates after fixating a table and process B + deletes the table at "the same time". The table fixation + could be done with <c>ets:safe_fixtable</c> or if process + A terminates in the middle of a long running + <c>select</c> or <c>match</c> call.</p> + <p> + Own Id: OTP-15109</p> + </item> + <item> + <p>Owner and group changes through + <c>file:write_file_info</c>, <c>file:change_owner</c>, + and <c>file:change_group</c> will no longer report + success on permission errors.</p> + <p> + *** POTENTIAL INCOMPATIBILITY ***</p> + <p> + Own Id: OTP-15118</p> + </item> + <item> + <p> + Fix a bug error reporting from escripts on windows where + the error message would get garbled.</p> + <p> + Own Id: OTP-15119 Aux Id: PR-1826 </p> + </item> + <item> + <p> + Fix segfault when a process is interally re-scheduled + while being traced for in out events. This bug was + introduced in erts-8.0 (OTP-19.0).</p> + <p> + Own Id: OTP-15125</p> + </item> + </list> + </section> + + + <section><title>Improvements and New Features</title> + <list> + <item> + <p>It is now possible to open device files and FIFOs with + <c>file:open/2</c>.</p> + <p> + Own Id: OTP-11462</p> + </item> + <item> + <p> + The <c>erlang:system_flag(scheduler_wall_time,Bool)</c> + call is now reference counted and will be turned off if + the (last) process that started the performance + statistics dies. Thus it is no longer possible to start + the statistics with <c>rpc:call(Node, erlang, + system_flag, [scheduler_wall_time, true])</c> since it + will be turned off directly afterwards when the rpc + process dies.</p> + <p> + *** POTENTIAL INCOMPATIBILITY ***</p> + <p> + Own Id: OTP-11694</p> + </item> + <item> + <p>A new logging API is added to Erlang/OTP, see the + <seealso + marker="kernel:logger"><c>logger(3)</c></seealso> manual + page, and section <seealso + marker="kernel:logger_chapter">Logging</seealso> in the + Kernel User's Guide.</p> + <p>Calls to <c>error_logger</c> are automatically + redirected to the new API, and legacy error logger event + handlers can still be used. It is, however, recommended + to use the Logger API directly when writing new code.</p> + <p>Notice the following potential incompatibilities:</p> + <list> <item><p>Kernel configuration parameters + <c>error_logger</c> still works, but is overruled if the + default handler's output destination is configured with + Kernel configuration parameter <c>logger</c>.</p> <p>In + general, parameters for configuring error logger are + overwritten by new parameters for configuring + Logger.</p></item> <item><p>The concept of SASL error + logging is deprecated, meaning that by default the SASL + application does not affect which log events are + logged.</p> <p>By default, supervisor reports and crash + reports are logged by the default Logger handler started + by Kernel, and end up at the same destination (terminal + or file) as other standard log event from Erlang/OTP.</p> + <p>Progress reports are not logged by default, but can be + enabled by setting the primary log level to info, for + example with the Kernel configuration parameter + <c>logger_level</c>.</p> <p>To obtain backwards + compatibility with the SASL error logging functionality + from earlier releases, set Kernel configuration parameter + <c>logger_sasl_compatible</c> to <c>true</c>. This + prevents the default Logger handler from logging any + supervisor-, crash-, or progress reports. Instead, SASL + adds a separate Logger handler during application start, + which takes care of these log events. The SASL + configuration parameters <c>sasl_error_logger</c> and + <c>sasl_errlog_type</c> specify the destination (terminal + or file) and severity level to log for these + events.</p></item></list> + <p> + Since Logger is new in Erlang/OTP 21.0, we do reserve the + right to introduce changes to the Logger API and + functionality in patches following this release. These + changes might or might not be backwards compatible with + the initial version.</p> + <p> + *** POTENTIAL INCOMPATIBILITY ***</p> + <p> + Own Id: OTP-13295</p> + </item> + <item> + <p> + <c>gen_sctp:connect_init/4</c> or rather connect in + <c>inet_drv.c</c> for SCTP has been fixed to not check + the write file descriptor for writeability after a + connect, since for SCTP (SOCK_SEQPACKET) that property + does not seem to be any kind of indicator for when a + connect has finished. This fixes connects that the OS + returned as "in progress" that was misinterpreted by + <c>gen_sctp:connect_init</c> as failed.</p> + <p> + Own Id: OTP-13760 Aux Id: PR-1592 </p> + </item> + <item> + <p>The file driver has been rewritten as a NIF, + decreasing the latency of file operations. Notable + incompatibilities are:</p> <list> <item><p>The + <c>use_threads</c> option for <c>file:sendfile/5</c> no + longer has any effect; we either use non-blocking + <c>sendfile(2)</c> or fall back to <c>file:read</c> + + <c>gen_tcp:send</c>. </p></item> <item><p>The + file-specific DTrace probes have been removed. The same + effect can be achieved with normal tracing together with + the <c>nif__entry</c>/<c>nif__return</c> probes to track + scheduling.</p></item> </list> + <p> + *** POTENTIAL INCOMPATIBILITY ***</p> + <p> + Own Id: OTP-14256</p> + </item> + <item> + <p>The I/O polling functionality of erts has been + re-written to better make use of the OSs polling + mechanisms. This change means that erts will now always + prefer to use a kernel-polling mechanism if possible. + Also all of the I/O polling has been moved to dedicated + threads instead of being placed in the scheduler + loops.</p> <p>As a result of this, the <c>erl</c> options + <c>+K</c> and <c>+secio</c> have been removed. It is + still possible to disable kernel-poll, but it has to be + done at compile time through the configure option + <c>--disable-kernel-poll</c>.</p> <p>The new <c>erl</c> + options <seealso marker="erl#+IOt"><c>+IOt</c></seealso> + and <seealso marker="erl#+IOp"><c>+IOp</c></seealso> can + be used to change how many IO poll threads and poll sets + that erts should use. See their respective documentation + for more details.</p> + <p> + Own Id: OTP-14346</p> + </item> + <item> + <p>Truly asynchronous auto-connect. Earlier, when + <c>erlang:send</c> was aimed toward an unconnected node, + the function would not return until the connection setup + had completed (or failed). Now the function returns + directly after the message has been enqueued and the + connection setup started.</p> + <p>The same applies to all distributed operations that + may trigger auto-connect, i.e. <c>'!'</c>, <c>send</c>, + <c>link</c>, <c>monitor</c>, <c>monitor_node</c>, + <c>exit/2</c> and <c>group_leader</c>.</p> + <p>The interface for all these functions are unchanged as + they do not return connection failures. The only + exception is <c>erlang:monitor</c> where a <em>possible + incompatibility</em> is introduced: An attempt to monitor + a process on a primitive node (such as erl_interface or + jinterface), where remote process monitoring is not + implemented, will no longer fail with <c>badarg</c> + exception. Instead a monitor will be created, but it will + only supervise the connection to the node.</p> + <p> + *** POTENTIAL INCOMPATIBILITY ***</p> + <p> + Own Id: OTP-14370</p> + </item> + <item> + <p>Changed the default behaviour of <c>.erlang</c> + loading: <c>.erlang</c> is no longer loaded from the + current directory. <c>c:erlangrc(PathList)</c> can be + used to search and load an <c>.erlang</c> file from user + specified directories.</p> <p><c>escript</c>, + <c>erlc</c>, <c>dialyzer</c> and <c>typer</c> no longer + load an <c>.erlang</c> at all.</p> + <p> + *** POTENTIAL INCOMPATIBILITY ***</p> + <p> + Own Id: OTP-14439</p> + </item> + <item> + <p> + New functionality for implementation of alternative + carriers for the Erlang distribution has been introduced. + This mainly consists of support for usage of distribution + controller processes (previously only ports could be used + as distribution controllers). For more information see + <seealso marker="erts:alt_dist#distribution_module">ERTS + User's Guide ➜ How to implement an Alternative Carrier + for the Erlang Distribution ➜ Distribution + Module</seealso>.</p> + <p> + Own Id: OTP-14459</p> + </item> + <item> + <p> + Add support for the lcc compiler and in extension the + Elbrus 2000 platform.</p> + <p> + Own Id: OTP-14492</p> + </item> + <item> + <p>Support for "tuple calls" have been removed from the + run-time system. Tuple calls was an undocumented and + unsupported feature which allowed the module argument for + an apply operation to be a tuple: <c>Var = dict:new(), + Var:size()</c>. This "feature" frequently caused + confusion, especially when such call failed. The + stacktrace would point out functions that don't exist in + the source code.</p> + <p>For legacy code that need to use parameterized modules + or tuple calls for some other reason, there is a new + compiler option called <c>tuple_calls</c>. When this + option is given, the compiler will generate extra code + that emulates the old behavior for calls where the module + is a variable.</p> + <p> + *** POTENTIAL INCOMPATIBILITY ***</p> + <p> + Own Id: OTP-14497</p> + </item> + <item> + <p>Creation of small maps with literal keys has been + optimized to be faster and potentially use less memory. + The keys are combined into a literal key tuple which is + put into the literal pool. The key tuple can be shared + between many instances of maps having the same keys.</p> + <p> + Own Id: OTP-14502</p> + </item> + <item> + <p> + When an exception is thrown, include the arguments of the + call in the stacktrace for BIFs <c>band</c>, <c>bor</c>, + <c>bsl</c>, <c>bsr</c>, <c>bxor</c>, <c>div</c>, + <c>rem</c> and the operators <c>+</c>, <c>-</c>, <c>*</c> + and <c>/</c>.</p> + <p> + *** POTENTIAL INCOMPATIBILITY ***</p> + <p> + Own Id: OTP-14508</p> + </item> + <item> + <p> + The non-smp emulators have been removed. This means that + the configure options <c>--disable-threads</c> and + <c>--enable-plain-emulator</c> have been removed and + configure will now refuse to build Erlang/OTP on + platforms without thread support.</p> + <p> + In order to achieve a similar setup as the non-smp + emulator, it is possible to start Erlang/OTP with the + <c>+S 1</c> option.</p> + <p> + *** POTENTIAL INCOMPATIBILITY ***</p> + <p> + Own Id: OTP-14518</p> + </item> + <item> + <p>Modules that use floating point constants compiled + with R15 or earlier will need to be re-compiled before + they can be loaded.</p> + <p> + Own Id: OTP-14575</p> + </item> + <item> + <p> + Implementation of true asynchronous signaling between + processes in order to improve scalability. Signals + affected include exit, monitor, demonitor, monitor + triggered, link, unlink, and group leader.</p> + <p> + Own Id: OTP-14589</p> + </item> + <item> + <p> + Added a PGO (profile guided optimization) pass to the + build step of erts. This can be disabled by passing + --disable-pgo to configure.</p> + <p> + Own Id: OTP-14604</p> + </item> + <item> + <p> + Improved the performance of <c>binary:split</c> and + <c>binary:match</c>.</p> + <p> + Own Id: OTP-14610 Aux Id: PR-1480 </p> + </item> + <item> + <p> + It is not longer possible to disable dirty schedulers + when building erlang.</p> + <p> + Own Id: OTP-14613</p> + </item> + <item> + <p>Loaded BEAM code in a 64-bit system requires less + memory because of better packing of operands for + instructions.</p> + <p>These memory savings were achieved by major + improvements to the <c>beam_makeops</c> scripts used when + building the run time system and BEAM compiler. There is + also new for documentation for <c>beam_makeops</c> that + describes how new BEAM instructions and loader + transformations can be implemented. The documentation is + found in here in a source directory or git repository: + erts/emulator/internal_doc/beam_makeops.md. An online + version can be found here: + https://github.com/erlang/otp/blob/master/erts/emulator/internal_doc/beam_makeops.md</p> + <p> + Own Id: OTP-14626</p> + </item> + <item> + <p><c>file:read_file</c> has been changed to read the + content of files that report a size of 0 even when data + can be read from them. An example of such a file is + <c>/proc/cpuinfo</c> on Linux.</p> + <p> + Own Id: OTP-14637 Aux Id: ERL-327 PR-1524 </p> + </item> + <item> + <p> + It is no longer possible to disable the <c>temp_alloc</c> + allocator. Disabling it caused serious performance + degradations and was never what was wanted.</p> + <p> + Own Id: OTP-14651</p> + </item> + <item> + <p>The reduction cost of sending messages is now + constant. It will no longer scale according to the length + of the receiving process' message queue.</p> + <p> + Own Id: OTP-14667</p> + </item> + <item> + <p> + Improved loading of modules with <c>-on_load</c> + directive, to no longer block all schedulers when the + load operation is completed.</p> + <p> + Own Id: OTP-14680</p> + </item> + <item> + <p> + On platforms with real-time signals available, SIGRTMIN+1 + is now used as the internal scheduler suspend signal + instead of SIGUSR2.</p> + <p> + Own Id: OTP-14682</p> + </item> + <item> + <p>When the value returned from a '<c>catch</c>' + expression is ignored, no stacktrace will be built if an + exception is caught. That will save time and produce less + garbage. There are also some minor optimizations of + '<c>try</c>/<c>catch</c>' both in the compiler and + run-time system.</p> + <p> + Own Id: OTP-14683</p> + </item> + <item> + <p>The guarantees and non-guarantees of + <c>erlang:get_stacktrace/0</c> are now documented.</p> + <p> + Own Id: OTP-14687</p> + </item> + <item> + <p>There is a new syntax in '<c>try/catch</c>' for + retrieving the stacktrace without calling + '<c>erlang:get_stacktrace/0</c>'. See the reference + manual for a description of the new syntax. The + '<c>erlang:get_stacktrace/0</c>' BIF is now + deprecated.</p> + <p> + Own Id: OTP-14692</p> + </item> + <item> + <p> + New 'used' option for <c>binary_to_term/2</c> that will + also return number of bytes actually read from the + binary. This enables easy access to any extra data in the + binary located directly after the returned term.</p> + <p> + Own Id: OTP-14780</p> + </item> + <item> + <p> + Added more statistics for + <c>erlang:system_info({allocator,A})</c> in the + <c>mbcs_pool</c> section.</p> + <p> + Own Id: OTP-14795 Aux Id: ERL-88 </p> + </item> + <item> + <p>Added <c>enif_ioq_peek_head</c> to retrieve Erlang + terms from NIF IO queues without having to resort to + copying.</p> + <p> + Own Id: OTP-14797</p> + </item> + <item> + <p>There is a new option '<c>makedep_side_effect</c>' for + the compiler and <c>-MMD</c> for '<c>erlc</c>' that + generates dependencies and continues to compile as + normal.</p> + <p> + Own Id: OTP-14830</p> + </item> + <item> + <p>Added <c>ets:whereis/1</c> for retrieving the table + identifier of a named table.</p> + <p> + Own Id: OTP-14884</p> + </item> + <item> + <p><c>seq_trace</c> labels may now be any erlang + term.</p> + <p> + Own Id: OTP-14899</p> + </item> + <item> + <p> + Optimized the common case of <c>monitor</c> followed by + <c>send</c> to the same local process. The monitor signal + is now delayed in order to be piggybacked with the sent + message and thereby only get one lock operation on the + message queue of the receiver. A delayed monitor signal + is flushed if no <c>send</c> has been done at the latest + when the process is scheduled out.</p> + <p> + Own Id: OTP-14901</p> + </item> + <item> + <p> + Make hipe compiled code work on x86_64 (amd64) with OS + security feature PIE, where executable code can be loaded + into a random location. Old behavior, if hipe was + enabled, was to disable PIE build options for the VM.</p> + <p> + Own Id: OTP-14903</p> + </item> + <item> + <p>The number of driver async threads will now default to + 1 as the standard drivers do not use them anymore. Users + that changed this value to tweak the file driver should + replace <c>+A</c> with <c>+SDio</c> since it now uses + dirty IO schedulers instead of async threads.</p> + <p> + *** POTENTIAL INCOMPATIBILITY ***</p> + <p> + Own Id: OTP-14928</p> + </item> + <item> + <p> + Optimize <c>==</c> and <c>/=</c> for binaries with + different sizes to be constant in time instead of + proportional to the size of their common prefix.</p> + <p> + Own Id: OTP-14934 Aux Id: PR-1708 </p> + </item> + <item> + <p> + Refactorings making some internal process flags available + for other usage.</p> + <p> + Own Id: OTP-14948</p> + </item> + <item> + <p> + Removed need for HiPE to allocate native executable + memory in low 2GB address space on x86_64. Command line + option <c>+MXscs</c> is thereby obsolete and ignored.</p> + <p> + Own Id: OTP-14951</p> + </item> + <item> + <p>Added <c>enif_make_map_from_arrays</c> for creating a + populated map, analogous to + <c>enif_make_list_from_array</c>.</p> + <p> + Own Id: OTP-14954</p> + </item> + <item> + <p>Added configuration switches for busy-wait and wake up + thresholds for dirty schedulers, and changing these + settings for normal schedulers will no longer affect + dirty schedulers. </p> <p>Refer to the documentation for + details. The new switches are <seealso + marker="erl#+sbwtdcpu">+sbwtdcpu</seealso>, <seealso + marker="erl#+sbwtdio">+sbwtdio</seealso>, <seealso + marker="erl#+swtdcpu">+swtdcpu</seealso>, and <seealso + marker="erl#+swtdio">+swtdio</seealso>.</p> <p>The + default busy wait threshold for dirty scheduler threads + has also been lowered to <c>short</c>.</p> + <p> + Own Id: OTP-14959</p> + </item> + <item> + <p> + The list of "taints" now also includes dynamic loaded + drivers in addition to NIF libraries. Statically linked + drivers and NIF libraries that are part of erts are not + included. The "taints" are returned by + <c>system_info(taints)</c> and printed in the header of + <c>erl_crash.dump</c> files.</p> + <p> + Own Id: OTP-14960</p> + </item> + <item> + <p>Added <c>instrument:allocations</c> and + <c>instrument:carriers</c> for retrieving information + about memory utilization and fragmentation.</p> + <p>The old <c>instrument</c> interface has been removed, + as have the related options <c>+Mim</c> and + <c>+Mis</c>.</p> + <p> + *** POTENTIAL INCOMPATIBILITY ***</p> + <p> + Own Id: OTP-14961</p> + </item> + <item> + <p>The process suspend functionality used by the <seealso + marker="erlang#suspend_process/2">erlang:suspend_process/2</seealso> + BIF has been reimplemented using the newly introduced + true asynchronous signaling between processes. This + mainly to reduce memory usage in the process control + block of all processes, but also in order to simplify the + implementation.</p> <warning> <p>You can easily create + deadlocks if processes suspends each other (directly or + in circles). In ERTS versions prior to ERTS version 10.0, + the runtime system prevented such deadlocks, but this + prevention has now been removed due to performance + reasons.</p> </warning> <p>Other ERTS internal + functionality that used the previous process suspend + functionality have also been reimplemented to use + asynchronous signaling instead.</p> + <p> + *** POTENTIAL INCOMPATIBILITY ***</p> + <p> + Own Id: OTP-14964 Aux Id: OTP-14589 </p> + </item> + <item> + <p>Added the <c>nifs</c> option to + <c>?MODULE:module_info/1</c> for listing a module's + installed NIF functions.</p> + <p> + Own Id: OTP-14965</p> + </item> + <item> + <p> + New implementation of <c>erlang:process_info/[1,2]</c>.</p> + <p> + In the general case when inspecting another process, the + new implementation sends an asynchronous process-info + request signal to the other process and waits for the + result instead of locking the other process and reading + the result directly. In some special cases where no + conflicts occur, signal order wont be violated, and the + amount of data requested is guaranteed to be small, the + inspected process may be inspected directly.</p> + <p> + Appropriate amount of reductions are now also bumped when + inspecting a process.</p> + <p> + Own Id: OTP-14966</p> + </item> + <item> + <p> + Removed process start time from crash dump in order to + save memory in process control block.</p> + <p> + Own Id: OTP-14975 Aux Id: PR-1597 </p> + </item> + <item> + <p> + Optimize <c>erlang:put/2</c> when updating existing key + with a new immediate value (atom, small integer, pid, + port).</p> + <p> + Own Id: OTP-14976</p> + </item> + <item> + <p> + <c>erlang:process_info/1</c> has been changed to no + longer include <c>messages</c> by default. Instead + <c>erlang:process_info/2</c> should be used.</p> + <p> + *** POTENTIAL INCOMPATIBILITY ***</p> + <p> + Own Id: OTP-14986 Aux Id: PR-1745 </p> + </item> + <item> + <p> + New <c>erlang:system_info(ets_count)</c> to get total + number of ets tables existing at the local node.</p> + <p> + Own Id: OTP-14987</p> + </item> + <item> + <p> + New NIF functions: <c>enif_mutex_name</c>, + <c>enif_cond_name</c>, <c>enif_rwlock_name</c>, + <c>enif_thread_name</c>, <c>enif_vfprintf</c>, + <c>enif_vsnprintf</c>.</p> + <p> + Own Id: OTP-14994</p> + </item> + <item> + <p>When <c>erlang:system_flag(backtrace_depth, 0)</c> has + been called, all exceptions will now contain the entry + for <em>one</em> function (despite the zero). It used to + be that a hand-made stack backtrace passed to + <c>erlang:raise/3</c> would be be truncated to an empty + list.</p> + <p> + Own Id: OTP-15026</p> + </item> + <item> + <p> + Fixed bug for named <c>ets</c> tables which could cause + unexpected results from matchspec iteration functions + (<c>ets:select*</c> and <c>ets:match*</c>) if the table + was deleted and recreated with the same name during the + iteration. The iteration could incorrectly continue + through the recreated table. The expected correct + behavior is now for the iteration call to fail with a + <c>badarg</c> exception if the table is deleted before + the iteration has completed.</p> + <p> + Own Id: OTP-15031</p> + </item> + <item> + <p>Two new guards BIFs operating on maps have been added: + <c>map_get/2</c> and <c>is_map_key/2</c>. They do the + same as <c>maps:get/2</c> and <c>maps:is_key/2</c>, + respectively, except that they are allowed to be used in + guards.</p> + <p> + Own Id: OTP-15037 Aux Id: PR-1784, PR-1802 </p> + </item> + <item> + <p> + Release run-queue lock while cleaning up terminated dirty + process.</p> + <p> + Own Id: OTP-15081</p> + </item> + <item> + <p>The callback module passed as <c>-epmd_module</c> to + erl has been expanded to be able to do name and port + resolving.</p> <p>Documentation has also been added in + the <seealso + marker="kernel:erl_epmd"><c>erl_epmd</c></seealso> + reference manual and ERTS User's Guide <seealso + marker="erts:alt_disco">How to Implement an Alternative + Service Discovery for Erlang Distribution</seealso>.</p> + <p> + Own Id: OTP-15086 Aux Id: PR-1694 </p> + </item> + </list> + </section> + +</section> + +<section><title>Erts 9.3.3.7</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> + Fixed bug in operator <c>band</c> of two negative + operands causing erroneous result if the absolute value + of one of the operands have the lowest <c>N*W</c> bits as + zero and the other absolute value is not larger than + <c>N*W</c> bits. <c>N</c> is an integer of 1 or larger + and <c>W</c> is 32 or 64 depending on word size.</p> + <p> + Own Id: OTP-15487 Aux Id: ERL-804 </p> + </item> + </list> + </section> + +</section> + +<section><title>Erts 9.3.3.6</title> + + <section><title>Improvements and New Features</title> + <list> + <item> + <p>List subtraction (The <c>--</c> operator) will now + yield properly on large inputs.</p> + <p> + Own Id: OTP-15371</p> + </item> + </list> + </section> + +</section> + +<section><title>Erts 9.3.3.5</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> + ERTS internal trees of monitor structures could get into + an inconsistent state. This could cause <c>'DOWN'</c> + messages not to be delivered when they should, as well as + delivery of <c>'DOWN'</c> messages that should not be + delivered.</p> + <p> + This bug was introduced in ERTS version 9.0 (OTP 20.0) + and was fixed in ERTS version 10.0 (OTP 21.0) due to a + rewrite of the monitor code. That is, this bug only exist + in the OTP 20 release.</p> + <p> + Own Id: OTP-15399 Aux Id: ERL-751, ERIERL-262, OTP-14205 </p> + </item> + </list> + </section> + +</section> + +<section><title>Erts 9.3.3.4</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> + Fixed bug in <c>ets:select_replace</c> when called with a + fully bound key could cause a following call to + <c>ets:next</c> or <c>ets:prev</c> to crash the emulator + or return invalid result.</p> + <p> + Own Id: OTP-15346</p> + </item> + </list> + </section> + +</section> + +<section><title>Erts 9.3.3.3</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> + Fixed a bug which caused an emulator crash when + <c>enif_send()</c> was called by a NIF that executed on a + dirty scheduler. The bug was either triggered when the + NIF called <c>enif_send()</c> without a message + environment, or when the process executing the NIF was + <c>send</c> traced.</p> + <p> + Own Id: OTP-15223</p> + </item> + <item> + <p> + Fixed a bug causing some Erlang references to be + inconsistently ordered. This could for example cause + failure to look up certain elements with references as + keys in search data structures. This bug was introduced + in R13B02.</p> + <p> + Thanks to Simon Cornish for finding the bug and supplying + a fix.</p> + <p> + *** POTENTIAL INCOMPATIBILITY ***</p> + <p> + Own Id: OTP-15225</p> + </item> + </list> + </section> + +</section> + +<section><title>Erts 9.3.3.2</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p>Fixed a race condition in the inet driver that could + cause receive to hang when the emulator was compiled with + gcc 8.</p> + <p> + Own Id: OTP-15158 Aux Id: ERL-654 </p> + </item> + <item> + <p> + Fix bug in generation of erl_crash.dump, which could + cause VM to crash.</p> + <p> + Bug exist since erts-9.2 (OTP-20.2).</p> + <p> + Own Id: OTP-15181</p> + </item> + </list> + </section> + +</section> + +<section><title>Erts 9.3.3.1</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p>Fixed a rare bug that could cause processes to be + scheduled after they had been freed.</p> + <p> + Own Id: OTP-15067 Aux Id: ERL-573 </p> + </item> + </list> + </section> + +</section> + +<section><title>Erts 9.3.3</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> + Fixed bug in <c>ets</c> that could cause VM crash if + process A terminates after fixating a table and process B + deletes the table at "the same time". The table fixation + could be done with <c>ets:safe_fixtable</c> or if process + A terminates in the middle of a long running + <c>select</c> or <c>match</c> call.</p> + <p> + Own Id: OTP-15109</p> + </item> + </list> + </section> + +</section> + +<section><title>Erts 9.3.2</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> + Fixed bug in <c>enif_binary_to_term</c> which could cause + memory corruption for immediate terms (atoms, small + integers, pids, ports, empty lists).</p> + <p> + Own Id: OTP-15080</p> + </item> + <item> + <p> + Fixed bug in <c>erlang:system_profile/2</c> that could + cause superfluous <c>{profile,_,active,_,_}</c> messages + for terminating processes.</p> + <p> + Own Id: OTP-15085</p> + </item> + </list> + </section> + +</section> + +<section><title>Erts 9.3.1</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p>Fixed a crash in <c>heart:get_cmd/0</c> when the + stored command was too long.</p> + <p> + Own Id: OTP-15034</p> + </item> + </list> + </section> + +</section> + +<section><title>Erts 9.3</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> + Fixed a <c>configure</c> test for <c>libz</c> internals + that unintentionally caused various native code in OTP to + link against <c>libz</c>. Under certain circumstances + this caused the build of OTP to fail.</p> + <p> + Own Id: OTP-14840 Aux Id: ERL-529 </p> + </item> + <item> + <p> + File names containing unicode codepoints larger than 255 + were not correctly encoded in stack traces.</p> + <p> + Own Id: OTP-14847 Aux Id: ERL-544 </p> + </item> + <item> + <p> + Fix HiPE bug for binary constructs like + <c><<X/utf8>></c> which could in rare cases + cause faulty results or VM crash.</p> + <p> + This fix affects both the <c>hipe</c> compiler and + <c>erts</c> runtime in an <em>incompatible</em> way. Old + hipe compiled files need to be recompiled to load and run + properly as native.</p> + <p> + *** POTENTIAL INCOMPATIBILITY ***</p> + <p> + Own Id: OTP-14850 Aux Id: PR-1664 </p> + </item> + <item> + <p> + Fix <c>term_to_binary/2</c> spec for + <c>minor_version</c>.</p> + <p> + Own Id: OTP-14876 Aux Id: ERL-548 </p> + </item> + <item> + <p> + Fix bug in erlang:binary_to_integer/2 where invalid + characters were not detected for bases larger then 10. + e.g. <c>binary_to_integer(<<":">>, 16)</c> + would return 3 and not badarg as it should.</p> + <p> + Own Id: OTP-14879</p> + </item> + <item> + <p>Fixed bug in <c>float_to_list/2</c> and + <c>float_to_binary/2</c> with option <c>decimals</c> that + caused a faulty rounding up of the last decimal digit for + about 6% of floats with a fraction part.</p> + <p>For example, <c>float_to_list(0.145, + [{decimals,1}])</c> returned <c>"0.2"</c> instead of + <c>"0.1"</c>.</p> + <p> + Own Id: OTP-14890</p> + </item> + <item> + <p> + Fix bug causing slow hipe execution in modules loaded + early during boot or loaded by <c>code:atomic_load</c> or + <c>code:finish_loading</c>.</p> + <p> + Own Id: OTP-14891</p> + </item> + <item> + <p>Fixed a buffer overflow in an internal string + formatting function that could be hit if specifying a + long floating-point format specifier to + <c>erts_sprintf</c> or similar.</p> + <p> + Own Id: OTP-14920</p> + </item> + <item> + <p><c>erlang:iolist_to_iovec/1</c> and + <c>enif_inspect_iovec</c> will no longer fail when + provided with binaries that have been matched-out on a + non-byte boundary.</p> + <p> + Own Id: OTP-14921</p> + </item> + <item> + <p><c>iolist_to_binary/1</c> and + <c>erlang:iolist_to_iovec/1</c> will now badarg if + supplied with a bitstring (without a list).</p> + <p> + Own Id: OTP-14926</p> + </item> + <item> + <p> + Reject loading modules with names containing directory + separators ('/' or '\' on Windows).</p> + <p> + Own Id: OTP-14933 Aux Id: ERL-564, PR-1716 </p> + </item> + <item> + <p> + Fix potential dead-lock when the tracer process dies + while a the traced process is running on a dirty + scheduler.</p> + <p> + Own Id: OTP-14938</p> + </item> + </list> + </section> + + + <section><title>Improvements and New Features</title> + <list> + <item> + <p> + More crash dump info such as: process binary virtual heap + stats, full info for process causing out-of-mem during + GC, more port related info, and dirty scheduler info.</p> + <p> + Own Id: OTP-14820</p> + </item> + </list> + </section> + +</section> + +<section><title>Erts 9.2.1</title> + + <section><title>Improvements and New Features</title> + <list> + <item> + <p> + Improve search algorithm of abandoned memory carriers. + Instead of limited linear search, each allocator instance + maintain a balanced search tree of all its abandoned + carriers for faster and more exhaustive search.</p> + <p> + Own Id: OTP-14915 Aux Id: ERIERL-88 </p> + </item> + <item> + <p> + New erts_alloc command line options <c>+M_acnl</c> and + <c>+M_acfml</c> to limit carrier abandonment.</p> + <p> + Own Id: OTP-14916 Aux Id: ERIERL-88 </p> + </item> + <item> + <p> + New family of <c>erts_alloc</c> strategies: Age Order + First Fit. Similar to "address order", but instead the + oldest possible carrier is always chosen for allocation.</p> + <p> + Own Id: OTP-14917 Aux Id: ERIERL-88 </p> + </item> + <item> + <p> + Add possibility to change allocator options at runtime + with <c>system_info(erts_alloc, ...)</c>. Only option + <c>sbct</c> (single block carrier threshold) is currently + supported via this interface.</p> + <p> + Own Id: OTP-14918 Aux Id: ERIERL-88 </p> + </item> + </list> + </section> + +</section> + +<section><title>Erts 9.2.0.1</title> + + <section><title>Improvements and New Features</title> + <list> + <item> + <p> + Extra internal consistency checks wrt communication with + erl_child_setup process.</p> + <p> + Own Id: OTP-15488 Aux Id: ERIERL-231 </p> + </item> + </list> + </section> + +</section> + +<section><title>Erts 9.2</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> + Fix a bug in tracing where the {caller} match spec + function would be set to undefined incorrectly when used + in conjunction with return_to or return_trace on some + functions.</p> + <p> + The functions effected are: erlang:put/2, erlang:erase/1, + erlang:process_info/1,2, erlang:nif_load/2, + erts_internal:garbage_collection/1 and + erts_internal:check_process_code/1.</p> + <p> + Because of this bug, the analysis done by fprof could + become incorrect when the functions above are the + tail-call in a function.</p> + <p> + Own Id: OTP-14677</p> + </item> + <item> + <p> + Fix emulator deadlock that would happen if + <c>trap_exit</c> was set to true and a process sends an + exit signal to itself using <c>exit(self(), Reason)</c> + while receive tracing was enabled for that process.</p> + <p> + Own Id: OTP-14678 Aux Id: ERL-495 </p> + </item> + <item> + <p>Writing of crash dumps is significantly faster.</p> + <p>Maps are now included in crash dumps.</p> + <p>Constants terms would only be shown in one process, + while other processes referencing the same constant term + would show a marker for incomplete heap. </p> + <p> + Own Id: OTP-14685 Aux Id: OTP-14611, OTP-14603, OTP-14595 </p> + </item> + <item> + <p> + The fallback home directory for windows has been changed + to be the PROFILE directory instead of the WINDOWS + directory. The fallback is used when the environment + variables HOMEDRIVE and HOMEPATH have not been set.</p> + <p> + Own Id: OTP-14691</p> + </item> + <item> + <p> + Fix bug for hipe compiled code using + <c><<X/utf32>></c> binary construction that + could cause faulty result or even VM crash.</p> + <p> + On architectures other than x86_64, code need to be + recompiled to benefit from this fix.</p> + <p> + Own Id: OTP-14740</p> + </item> + <item> + <p> + Fixed bug in <c>erlang:garbage_collect/2</c> and + <c>erlang:check_process_code/3</c>, when called with + option <c>{async,ReqestId}</c>. Could cause VM crash or + heap corruption if <c>RequestId</c> was an immediate term + (like a pid, atom or small integer). Bug exists since + OTP-17.0.</p> + <p> + Own Id: OTP-14752</p> + </item> + <item> + <p>ERL_NIF_MINOR_VERSION wasn't bumped with the addition + of <c>enif_ioq_*</c>.</p> + <p> + Own Id: OTP-14779</p> + </item> + <item> + <p>Purging of loaded code that contained "fake literals" + (for example the magic reference obtained from + '<c>ets:new/2</c>') would crash the runtime system. + Corrected.</p> + <p> + Own Id: OTP-14791</p> + </item> + <item> + <p>Setting the size of the atom table to a number near + 2147483647 (using the '<c>+t</c>' option) would cause the + emulator to exit with a failure to allocate a huge amount + of memory. This has been corrected. Also the usage + message for the '<c>+t</c>' option has been corrected to + show the correct upper limit 2147483647 instead of 0.</p> + <p> + Own Id: OTP-14796</p> + </item> + <item> + <p>Fixed a bug that prevented registered process names + from being resolved in lcnt results.</p> + <p> + Own Id: OTP-14803</p> + </item> + <item> + <p>Formatting bugs were fixed in several HiPE debug + BIFs.</p> + <p> + Own Id: OTP-14804</p> + </item> + </list> + </section> + + + <section><title>Improvements and New Features</title> + <list> + <item> + <p>Binaries and some other data in crash dumps are now + encoded in base64 (instead of in hex), which will reduce + the size of crash dumps.</p> + <p>A few bugs in the handling of sub binaries in + <c>crashdump_viewer</c> have been fixed.</p> + <p> + Own Id: OTP-14686</p> + </item> + <item> + <p> + Micro optimization for send operations of messages to + other nodes. The local ack-message, which is otherwise + sent back from TPC/IP port driver to sending client + process, is now ignored earlier for distributed send + operations.</p> + <p> + Own Id: OTP-14689</p> + </item> + </list> + </section> + +</section> + +<section><title>Erts 9.1.5</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p>Fixed a bug in file closure on Unix; close(2) was + retried on EINTR which could cause a different (recently + opened) file to be closed as well.</p> + <p> + Own Id: OTP-14775</p> + </item> + <item> + <p> + A race-condition when tearing down a connection with + active node monitors could cause the runtime system to + crash.</p> + <p> + This bug was introduced in ERTS version 8.0 (OTP 19.0).</p> + <p> + Own Id: OTP-14781 Aux Id: OTP-13047 </p> + </item> + </list> + </section> + +</section> + +<section><title>Erts 9.1.4</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p>Microstate accounting sometimes produced incorrect + results for dirty schedulers.</p> + <p> + Own Id: OTP-14707</p> + </item> + <item> + <p>Fixed a regression in <c>zlib:gunzip/1</c> that + prevented it from working when the decompressed size was + a perfect multiple of 16384. This regression was + introduced in 20.1.1</p> + <p> + Own Id: OTP-14730 Aux Id: ERL-507 </p> + </item> + <item> + <p>Fixed a memory corruption bug in + <c>enif_inspect_iovec</c>; writable binaries stayed + writable after entering the iovec.</p> + <p> + Own Id: OTP-14745</p> + </item> + <item> + <p>Fixed a crash in <c>enif_inspect_iovec</c> on + encountering empty binaries.</p> + <p> + Own Id: OTP-14750</p> + </item> + <item> + <p><c>zlib:deflateParams/3</c> will no longer return + <c>buf_error</c> when called after <c>zlib:deflate/2</c> + with zlib <c>1.2.11</c>.</p> + <p> + Own Id: OTP-14751</p> + </item> + </list> + </section> + +</section> + +<section><title>Erts 9.1.3</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p>Added zlib:set_controlling_process/2 to move a + zstream() between processes.</p> + <p> + Own Id: OTP-14672 Aux Id: ERL-494 </p> + </item> + <item> + <p> + Fix so that schedulers are bound correctly when the first + available cpu is not the first detected cpu. e.g. when + using "taskset -c X..Y" when X is not equal to 0.</p> + <p> + Own Id: OTP-14694</p> + </item> + </list> + </section> + +</section> + +<section><title>Erts 9.1.2</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> + Fixed bug that could cause a VM crash when a corrupt + message is received on distribution channel from other + node.</p> + <p> + Own Id: OTP-14661 Aux Id: ERIERL-80 </p> + </item> + </list> + </section> + +</section> + +<section><title>Erts 9.1.1</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p>The new zlib module returned a data_error when + inflating concatenated streams, which was incompatible + with the old module's behavior of returning the + uncompressed data up to the end of the first stream.</p> + <p> + Own Id: OTP-14648</p> + </item> + <item> + <p>zlib:gunzip/1 will no longer stop at the end of the + first stream when decompressing concatenated gzip + files.</p> + <p> + Own Id: OTP-14649</p> + </item> + </list> + </section> + +</section> + +<section><title>Erts 9.1</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> + Changed <c>erlang:apply/2</c> to raise a <c>badarg</c> + exception if the second argument is not a proper list. + Previous behavior was a misleading <c>undef</c> + exception.</p> + <p> + Own Id: OTP-14490 Aux Id: ERL-432 </p> + </item> + <item> + <p>On macOS, <c>crypto</c> would crash if <c>observer</c> + had been started before <c>crypto</c>. On the beta for + macOS 10.13 (High Sierra), <c>crypto</c> would crash. + Both of those bugs have been fixed.</p> + <p> + Own Id: OTP-14499 Aux Id: ERL-251 ERL-439 </p> + </item> + <item> + <p> + Fixed bug in enif_whereis_pid/port that could cause heap + corruption in rare cases.</p> + <p> + Own Id: OTP-14523</p> + </item> + <item> + <p> + Fix so that trace messages generated when in a dirty nif + are flushed correctly when the dirty nif is done + executing.</p> + <p> + Own Id: OTP-14538</p> + </item> + <item> + <p> + Fix escape code handling when using ANSI color codes in + the shell.</p> + <p> + Own Id: OTP-14549 Aux Id: PR1536 </p> + </item> + <item> + <p> + Upgraded the ERTS internal PCRE library from version 8.40 + to version 8.41. See <url + href="http://pcre.org/original/changelog.txt">http://pcre.org/original/changelog.txt</url> + for information about changes made to PCRE. This library + implements major parts of the <seealso + marker="stdlib:re"><c>re</c></seealso> regular + expressions module.</p> + <p> + Own Id: OTP-14574</p> + </item> + <item> + <p> + Fixed a bug causing <c>statistics(runtime)</c> to produce + negative values and a bug in + <c>statistics(wall_clock)</c> causing it to produce + values one second too long.</p> + <p> + <c>statistics(runtime)</c> now also use + <c>getrusage()</c> as source when available preventing + the returned value from wrapping as frequent as before.</p> + <p> + Own Id: OTP-14597 Aux Id: ERL-465 </p> + </item> + <item> + <p> + Fixed small memory leak that could occur when sending to + a terminating port.</p> + <p> + Own Id: OTP-14609</p> + </item> + <item> + <p> + Fix bug causing VM crash when a module with + <c>-on_load</c> directive is loaded while + <c>erlang:trace(on_load, ...)</c> is enabled.</p> + <p> + Own Id: OTP-14612</p> + </item> + <item> + <p>A warning that the compiler may optimize away atoms + have been added to the documentation of + <c>list_to_existing_atom/1</c> and + <c>binary_to_existing_atom/2</c>.</p> + <p> + Own Id: OTP-14614 Aux Id: ERL-453 </p> + </item> + </list> + </section> + + + <section><title>Improvements and New Features</title> + <list> + <item> + <p>Lock counting can now be fully toggled at runtime in + the lock counting emulator (<c>-emu_type lcnt</c>). + Everything is enabled by default to match the old + behavior, but specific categories can be toggled at will + with minimal runtime overhead when disabled. Refer to the + documentation on <c>lcnt:rt_mask/1</c> for details.</p> + <p> + Own Id: OTP-13170</p> + </item> + <item> + <p>The <c>zlib</c> module has been refactored and all its + operations will now yield appropriately, allowing them to + be used freely in concurrent applications.</p> <p>The + following functions have been deprecated, but will not + produce compiler warnings until OTP 21: + <c>zlib:adler32</c>, <c>zlib:crc32</c>, + <c>zlib:inflateChunk</c>, <c>zlib:getBufSize</c>, + <c>zlib:setBufSize</c>.</p> <p>The behavior of throwing + an error when a dictionary is required for decompression + has also been deprecated. Refer to the documentation on + <c>inflateSetDictionary/2</c> for details.</p> + <p> + Own Id: OTP-14185</p> + </item> + <item> + <p><c>lcnt:collect</c> and <c>lcnt:clear</c> will no + longer block all other threads in the runtime system.</p> + <p> + Own Id: OTP-14412</p> + </item> + <item> + <p>Add <c>erlang:iolist_to_iovec/1</c>, which converts an + iolist() to an erlang:iovec(), which suitable for use + with <c>enif_inspect_iovec</c>.</p> + <p> + Own Id: OTP-14520</p> + </item> + <item> + <p>When provided with bad arguments, the <c>zlib</c> + module will now raise named exceptions instead of just + <c>badarg</c>. For example, <c>not_initialized</c> when + using <c>zlib:inflate/2</c> with an uninitialized + stream.</p> + <p> + Own Id: OTP-14527</p> + </item> + <item> + <p> + <c>erlang:halt/2</c> allows any Unicode string as slogan + for the crash dump.</p> + <p> + Own Id: OTP-14553</p> + </item> + <item> + <p>Add new nif API functions for managing an I/O Queue. + The added functions are:</p> <list type="bulleted"> + <item><seealso marker="erl_nif#enif_ioq_create"> + <c>enif_ioq_create()</c></seealso></item> <item><seealso + marker="erl_nif#enif_ioq_destroy"> + <c>enif_ioq_destroy()</c></seealso></item> <item><seealso + marker="erl_nif#enif_ioq_enq_binary"> + <c>enif_ioq_enq_binary()</c></seealso></item> + <item><seealso marker="erl_nif#enif_ioq_enqv"> + <c>enif_ioq_enqv()</c></seealso></item> <item><seealso + marker="erl_nif#enif_ioq_deq"> + <c>enif_ioq_deq()</c></seealso></item> <item><seealso + marker="erl_nif#enif_ioq_peek"> + <c>enif_ioq_peek()</c></seealso></item> <item><seealso + marker="erl_nif#enif_inspect_iovec"> + <c>enif_inspect_iovec()</c></seealso></item> + <item><seealso marker="erl_nif#enif_free_iovec"> + <c>enif_free_iovec()</c></seealso></item> </list> + <p> + Own Id: OTP-14598</p> + </item> + </list> + </section> + +</section> + +<section><title>Erts 9.0.5</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> + Fixed bug in <c>binary_to_term</c> and + <c>binary_to_atom</c> that could cause VM crash. + Typically happens when the last character of an UTF8 + string is in the range 128 to 255, but truncated to only + one byte. Bug exists in <c>binary_to_term</c> since ERTS + version 5.10.2 (OTP_R16B01) and <c>binary_to_atom</c> + since ERTS version 9.0 (OTP-20.0).</p> + <p> + Own Id: OTP-14590 Aux Id: ERL-474 </p> + </item> + </list> + </section> + +</section> + +<section><title>Erts 9.0.4</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> + A timer internal bit-field used for storing scheduler id + was too small. As a result, VM internal timer data + structures could become inconsistent when using 1024 + schedulers on the system. Note that systems with less + than 1024 schedulers are not effected by this bug.</p> + <p> + This bug was introduced in ERTS version 7.0 (OTP 18.0).</p> + <p> + Own Id: OTP-14548 Aux Id: OTP-11997, ERL-468 </p> + </item> + <item> + <p> + Automatic cleanup of a BIF timer, when the owner process + terminated, could race with the timeout of the timer. + This could cause the VM internal data structures to + become inconsistent which very likely caused a VM crash.</p> + <p> + This bug was introduced in ERTS version 9.0 (OTP 20.0).</p> + <p> + Own Id: OTP-14554 Aux Id: OTP-14356, ERL-468 </p> + </item> + </list> + </section> + +</section> + +<section><title>Erts 9.0.3</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p>Binary append operations did not check for overflow, + resulting in nonsensical results when huge binaries were + appended.</p> + <p> + Own Id: OTP-14524</p> + </item> + </list> + </section> + +</section> + +<section><title>Erts 9.0.2</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> + Added missing release notes for OTP-14491 ("performance + bug in pre-allocators") which was included in erts-9.0.1 + (OTP-20.0.1).</p> + <p> + Own Id: OTP-14494</p> + </item> + <item> + <p>Fixed a bug that prevented TCP sockets from being + closed properly on send timeouts.</p> + <p> + Own Id: OTP-14509</p> + </item> + <item> + <p> + Fixed bug in operator <c>bxor</c> causing erroneuos + result when one operand is a big <em>negative</em> + integer with the lowest <c>N*W</c> bits as zero and the + other operand not larger than <c>N*W</c> bits. <c>N</c> + is an integer of 1 or larger and <c>W</c> is 32 or 64 + depending on word size.</p> + <p> + Own Id: OTP-14514</p> + </item> + </list> + </section> + +</section> + +<section><title>Erts 9.0.1</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> + Fixed a bug in gen_tcp:send where it never returned when + repeatedly called on a remotely closed TCP socket.</p> + <p> + Own Id: OTP-13939 Aux Id: ERL-193 </p> + </item> + <item> + <p> + Fixed segfault that could happen during cleanup of + aborted erlang:port_command/3 calls. A port_command is + aborted if the port is closed at the same time as the + port_command was issued. This bug was introduced in + erts-8.0.</p> + <p> + Own Id: OTP-14481</p> + </item> + <item> + <p> + Fixed implementation of <c>statistics(wall_clock)</c> and + <c>statistics(runtime)</c> so that values do not + unnecessarily wrap due to the emulator. Note that the + values returned by <c>statistics(runtime)</c> may still + wrap due to limitations in the underlying functionality + provided by the operating system.</p> + <p> + Own Id: OTP-14484</p> + </item> + <item> + <p> + Fix performance bug in pre-allocators that could cause + them to permanently fall back on normal more expensive memory + allocation. Pre-allocators are used for quick allocation + of short lived meta data used by messages and other + scheduled tasks. Bug exists since OTP_R15B02. + [this release note was missing in erts-9.0.1]</p> + <p> + Own Id: OTP-14491</p> + </item> + </list> + </section> + +</section> + +<section><title>Erts 9.0</title> + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p>Fix various bugs regarding loading, upgrade and purge + of HiPE compiled code:</p> <list> <item>The native code + memory for a purged module was never deallocated.</item> + <item>Wrong functions could in some cases be called after + a module upgrade.</item> + <item><c>erlang:check_process_code</c> did not check for + recursive calls made from native code.</item> </list> + <p> + Own Id: OTP-13968</p> + </item> + <item> + <p> + Hipe optional LLVM backend does require LLVM version 3.9 + or later as older versions forced strong dependencies on + erts internals structures.</p> + <p> + Own Id: OTP-14238</p> + </item> + <item> + <p>When an exception such as '<c>throw(HugeTerm)</c>' was + caught, <c>HugeTerm</c> term would be kept in the process + until the next exception occurred, potentially increasing + the heap size for the process. That has been + corrected.</p> + <p> + Own Id: OTP-14255 Aux Id: OTP-14400, OTP-14401 </p> + </item> + <item> + <p> + Slogans in crash dumps have been extended to print more + complex terms.</p> + <p> + Own Id: OTP-14303</p> + </item> + <item> + <p> + Fixed bug when using <c>enif_inspect_binary</c> in + combination with <c>enif_copy</c>. In some circumstances + the inspected binary could be reallocated by the + <c>enif_copy</c> call when it shouldn't have been.</p> + <p> + Own Id: OTP-14304</p> + </item> + <item> + <p> + The address family <c>local</c> (AF_UNIX / AF_LOCAL) now + does not ensure zero termination of Linux Abstract + Addresses so they can use all bytes.</p> + <p> + Own Id: OTP-14305</p> + </item> + <item> + <p> + Use <c>-fno-PIE</c> for Gentoo Hardened and others that + don't accept linker flag <c>-no-pie</c>.</p> + <p> + Own Id: OTP-14307 Aux Id: PR-1379 </p> + </item> + <item> + <p> + Disable hipe for <c>ppc64le</c> architecture (little + endian) as it is not, and has never been, supported. It + was earlier equated with <c>ppc64</c> (big endian) which + lead to broken build without <c>--disable-hipe</c>.</p> + <p> + Own Id: OTP-14314 Aux Id: ERL-369, PR-1394 </p> + </item> + <item> + <p> + Fix 'epmd -kill' to return a failure exit status code if + epmd was not killed because of some error.</p> + <p> + Own Id: OTP-14324</p> + </item> + <item> + <p>Fixed the following dirty scheduler related bugs:</p> + <list> <item><p>the <c>+SDPcpu</c> command line argument + could cause the amount of dirty CPU schedulers to be set + to zero</p></item> + <item><p><c>erlang:system_flag(multi_scheduling, _)</c> + failed when only one normal scheduler was used together + with dirty scheduler support</p></item> </list> + <p> + Own Id: OTP-14335</p> + </item> + <item> + <p> + Fix erlexec to handle mismatch in sysconf and proc fs + when figuring out the cpu topology. This behaviour has + been seen when using docker together with + <c>--cpuset-cpus</c>.</p> + <p> + Own Id: OTP-14352</p> + </item> + <item> + <p> + Fixed memory segment cache used for multiblock carriers. + Huge (> 2GB) memory segments could cause a VM crash. + Creation of such huge memory segments used for multiblock + carriers is however very uncommon.</p> + <p> + Own Id: OTP-14360 Aux Id: ERL-401, PR-1417 </p> + </item> + <item> + <p> + Fix bug causing <c>code:is_module_native</c> to falsely + return true when <c>local</c> call trace is enabled for + the module.</p> + <p> + Own Id: OTP-14390</p> + </item> + <item> + <p> + Fix emulator crash when receive tracing on a + <c>trace_delivered</c> message.</p> + <p> + Own Id: OTP-14411</p> + </item> + <item> + <p> + Fix file:sendfile error handling on SunOS when a + connection is closed during transmission.</p> + <p> + Own Id: OTP-14424</p> + </item> + <item> + <p> + <c>escript</c> did not handle paths with spaces correct.</p> + <p> + Own Id: OTP-14433</p> + </item> + <item> + <p> + Fix erroneous lock check assertion when <c>wx</c> is run + on MacOS X.</p> + <p> + Own Id: OTP-14437 Aux Id: ERL-360 </p> + </item> + <item> + <p>Active-mode TCP sockets are now cleaned up properly on + send/shutdown errors.</p> + <p> + Own Id: OTP-14441 Aux Id: ERL-430 </p> + </item> + <item> + <p> + Fix compilation of hipe_mkliterals when the LIBS + configure variable had to be set.</p> + <p> + Own Id: OTP-14447</p> + </item> + </list> + </section> + + + <section><title>Improvements and New Features</title> + <list> + <item> + <p> + Added <c>erlang:garbage_collect/2</c> that takes an + option list as the last argument that can be used to + control whether a minor or a major garbage collection is + to be done. Doing a minor collection only collects terms + that have recently died, but is cheaper than a major + collection.</p> + <p> + Own Id: OTP-11695</p> + </item> + <item> + <p> + Optimized test for tuples with an atom as first element.</p> + <p> + Own Id: OTP-12148</p> + </item> + <item> + <p> + Erlang literals are no longer copied during process to + process messaging.</p> + <p> + Own Id: OTP-13529</p> + </item> + <item> + <p>Add support in the <c>erl_nif</c> API for asynchronous + message notifications when sockets or other file + descriptors are ready to accept read or write operations. + The following functions have been added:</p> <list> + <item><p>enif_select</p></item> + <item><p>enif_monitor_process</p></item> + <item><p>enif_demonitor_process</p></item> + <item><p>enif_compare_monitors</p></item> + <item><p>enif_open_resource_type_x</p></item> </list> + <p> + Own Id: OTP-13684</p> + </item> + <item> + <p>There are two new guard BIFs '<c>floor/1</c>' and + '<c>ceil/1</c>'. They both return integers. In the + '<c>math</c>' module, there are two new BIFs with the + same names that return floating point values.</p> + <p> + Own Id: OTP-13692</p> + </item> + <item> + <p> + Remove deprecated <c>erlang:hash/2</c>.</p> + <p> + *** POTENTIAL INCOMPATIBILITY ***</p> + <p> + Own Id: OTP-13827</p> + </item> + <item> + <p>Replaced usage of deprecated symbolic <seealso + marker="erts:erlang#type-time_unit"><c>time + unit</c></seealso> representations.</p> + <p> + Own Id: OTP-13831 Aux Id: OTP-13735 </p> + </item> + <item> + <p> + Added support in zlib for extraction of the inflation + dictionary.</p> + <p> + Own Id: OTP-13842</p> + </item> + <item> + <p> + The previously used purge strategy has been removed. The + optional purge strategy introduced in ERTS version 8.1 is + now the only strategy available.</p> + <p> + The new purge strategy is slightly incompatible with the + old strategy. Previously processes holding <c>fun</c>s + that referred to the module being purged either failed a + soft purge, or was killed during a hard purge. The new + strategy completely ignores <c>fun</c>s. If <c>fun</c>s + referring to the code being purged exist, and are used + after a purge, an exception will be raised upon usage. + That is, the behavior will be exactly the same as the + case when a <c>fun</c> is received by a process after the + purge.</p> + <p> + For more information see the documentation of <seealso + marker="erts:erlang#check_process_code/3"><c>erlang:check_process_code/3</c></seealso>.</p> + <p> + *** POTENTIAL INCOMPATIBILITY ***</p> + <p> + Own Id: OTP-13844 Aux Id: OTP-13833 </p> + </item> + <item> + <p> + Dirty schedulers are now enabled by default when the + runtime system is built with SMP support.</p> + <p> + Own Id: OTP-13860</p> + </item> + <item> + <p> + Improved ETS lookup/insert/delete speed for large + <c>set</c>, <c>bag</c> and <c>duplicate_bag</c> by a + significant reduction of the hash load factor. This speed + improvement comes at the expense of less than one word + per table entry. Tables with less than 256 entries are + not affected at all.</p> + <p> + Own Id: OTP-13903</p> + </item> + <item> + <p> + The NIF library <c>reload</c> feature is not supported + anymore. It has been marked as deprecated since OTP R15B. + This means that you are only allowed to do one successful + call to <c>erlang:load_nif/2</c> for each module + instance. A second call to <c>erlang:load_nif/2</c> will + return <c>{error, {reload, _}}</c> even if the NIF + library implements the <c>reload</c> callback.</p> + <p> + Runtime upgrade of a NIF library is still supported by + using the Erlang module upgrade mechanics with a current + and an old module instance existing at the same time with + their corresponding NIF libraries.</p> + <p> + *** POTENTIAL INCOMPATIBILITY ***</p> + <p> + Own Id: OTP-13908</p> + </item> + <item> + <p> + Add <c>erlang:system_info(atom_count)</c> and + <c>erlang:system_info(atom_limit)</c> to provide a way to + retrieve the current and maximum number of atoms.</p> + <p> + Own Id: OTP-13976</p> + </item> + <item> + <p>The function <c>fmod/2</c> has been added to the + <c>math</c> module.</p> + <p> + Own Id: OTP-14000</p> + </item> + <item> + <p> + <c>erlang:load_nif/2</c> returns new error type + <c>notsup</c> when called for a HiPE compiled module, + which is not supported.</p> + <p> + Own Id: OTP-14002</p> + </item> + <item> + <p> + Add driver and nif lock instrumentation to lcnt</p> + <p> + Own Id: OTP-14069</p> + </item> + <item> + <p> + Reduce memory pressure by converting sub-binaries to + heap-binaries when possible. This is done during garbage + collection.</p> + <p> + Own Id: OTP-14149</p> + </item> + <item> + <p> + Dirty schedulers are now enabled and supported on Erlang + runtime systems with SMP support.</p> + <p> + Besides support for dirty NIFs also support for dirty + BIFs and dirty garbage collection have been introduced. + All garbage collections that potentially will take a long + time to complete are now performed on dirty schedulers if + enabled.</p> + <p> + <seealso + marker="erts:erlang#statistics/1"><c>erlang:statistics/1</c></seealso> + with arguments inspecting scheduler and run queue states + have been changed due to the dirty scheduler support. + Code using this functionality may have to be rewritten + taking these incompatibilities into consideration. + Examples of such uses are calls to <seealso + marker="erts:erlang#statistics_scheduler_wall_time"><c>erlang:statistics(scheduler_wall_time)</c></seealso>, + <seealso + marker="erts:erlang#statistics_total_run_queue_lengths"><c>statistics(total_run_queue_lengths)</c></seealso>, + <seealso + marker="erts:erlang#statistics_total_active_tasks"><c>statistics(total_active_tasks)</c></seealso>, + etc.</p> + <p> + *** POTENTIAL INCOMPATIBILITY ***</p> + <p> + Own Id: OTP-14152</p> + </item> + <item> + <p>Atoms may now contain arbitrary Unicode + characters.</p> + <p> + Own Id: OTP-14178</p> + </item> + <item> + <p> + Introduce an event manager in Erlang to handle OS + signals. A subset of OS signals may be subscribed to and + those are described in the Kernel application.</p> + <p> + Own Id: OTP-14186</p> + </item> + <item> + <p> + The <c>escript</c> program now handles symbolic links to + escripts.</p> + <p> + This is useful for standalone systems with + <c>escript</c>s residing on a bin directory not included + in the execution path (as it may cause their <c>erl</c> + program(s) to override the desired one). Instead the + <c>escript</c>s can be referred to via symbolic links + from a bin directory in the path.</p> + <p> + Own Id: OTP-14201 Aux Id: PR-1293 </p> + </item> + <item> + <p> + All uses of the magic binary kludge has been replaced by + uses of erlang references.</p> + <p> + A magic binary was presented as an empty binary, but + actually referred other data internally in the Erlang VM. + Since they were presented as empty binaries, different + magic binaries compared as equal, and also lost their + internal data when passed out of an erlang node.</p> + <p> + The new usage of references has not got any of these + strange semantic issues, and the usage of these + references has been optimized to give the same + performance benefits as well as memory usage benefits as + magic binaries had.</p> + <p> + A couple of examples of previous uses of magic binaries + are match specifications and NIF resources.</p> + <p> + Own Id: OTP-14205</p> + </item> + <item> + <p> + The non-smp emulators have been deprecated and are + scheduled for removal in OTP-21.</p> + <p> + In preparation for this, the threaded non-smp emulator is + no longer built by default and has to be enabled using + the --enable-plain-emulator to configure.</p> + <p> + *** POTENTIAL INCOMPATIBILITY ***</p> + <p> + Own Id: OTP-14272</p> + </item> + <item> + <p> + Allow HiPE to run on VM built with + <c>--enable-m32-build</c>.</p> + <p> + Own Id: OTP-14330 Aux Id: PR-1397 </p> + </item> + <item> + <p> + Upgraded the OTP internal PCRE library from version 8.33 + to version 8.40. This library is used for implementation + of the <seealso marker="stdlib:re"><c>re</c></seealso> + regular expressions module.</p> + <p> + Besides various bug fixes, the new version allows for + better stack protection. In order to utilize this + feature, the stack size of normal scheduler threads is + now by default set to 128 kilo words on all platforms. + The stack size of normal scheduler threads can be set + upon system start by passing the <seealso + marker="erts:erl#sched_thread_stack_size"><c>+sss</c></seealso> + command line argument to the <seealso + marker="erts:erl"><c>erl</c></seealso> command.</p> + <p> + See <url + href="http://pcre.org/original/changelog.txt">http://pcre.org/original/changelog.txt</url> + for information about changes made to PCRE between the + versions 8.33 and 8.40.</p> + <p> + *** POTENTIAL INCOMPATIBILITY ***</p> + <p> + Own Id: OTP-14331 Aux Id: ERL-208 </p> + </item> + <item> + <p> + Remove generation of atoms in old latin1 external format + in the distribution between erlang nodes, + <c>erl_interface</c>, and <c>jinterface</c>. The new utf8 + format for atoms was introduced in OTP R16. An OTP 20 + node can therefore not connect to nodes older than R16.</p> + <p> + Atoms that can be encoded using latin1 are still encoded + by <c>term_to_binary()</c> using latin1 encoding. Note + that all atoms will by default be encoded using utf8 in a + future Erlang/OTP release. For more information see the + documentation of <seealso + marker="erts:erlang#term_to_binary/2"><c>erlang:term_to_binary/2</c></seealso>.</p> + <p> + Own Id: OTP-14337</p> + </item> + <item> + <p> + Added function <c>re:version/0</c> which returns + information about the OTP internal PCRE version used for + implementation of the <c>re</c> module.</p> + <p> + Own Id: OTP-14347 Aux Id: PR-1412 </p> + </item> + <item> + <p> + Added new debug bif <c>erlang:list_to_port/1</c>.</p> + <p> + Own Id: OTP-14348</p> + </item> + <item> + <p> + Various improvements of timer management internally in + the VM. These improvements both reduced memory + consumption of timer wheels as well as reduce the amount + of work that has to be performed in order to handle + timers.</p> + <p> + Own Id: OTP-14356</p> + </item> + <item> + <p> Sockets can now be bound to device (SO_BINDTODEVICE) + on platforms where it is supported. </p> <p> This has + been implemented e.g to support VRF-Lite under Linux; see + <url + href="https://www.kernel.org/doc/Documentation/networking/vrf.txt"> + VRF </url>, and GitHub pull request <url + href="https://github.com/erlang/otp/pull/1326">#1326</url>. + </p> + <p> + Own Id: OTP-14357 Aux Id: PR-1326 </p> + </item> + <item> + <p>Added the following <seealso + marker="erl"><c>erl</c></seealso> command line arguments + with which you can set suggested stack for dirty + schedulers:</p> <taglist> <tag><seealso + marker="erl#dcpu_sched_thread_stack_size"><c>+sssdcpu</c></seealso></tag> + <item><p>for dirty CPU schedulers</p></item> + <tag><seealso + marker="erl#dio_sched_thread_stack_size"><c>+sssdio</c></seealso></tag> + <item><p>for dirty IO schedulers</p></item> </taglist> + <p>The default suggested stack size for dirty schedulers + is 40 kilo words.</p> + <p> + Own Id: OTP-14380</p> + </item> + <item> + <p> + Changed erts startup program name, argv 0, to use the + environment variable <c>ESCRIPT_NAME</c> so that + <c>erlc</c>, <c>dialyzer</c>, <c>typer</c>, + <c>ct_run</c>, or the escript name can be seen with + external programs, such as ps and htop (depending on + options), on unix.</p> + <p> + Own Id: OTP-14381</p> + </item> + <item> + <p> + Improvements of <c>escript</c> documentation.</p> + <p> + Own Id: OTP-14384 Aux Id: OTP-14201 </p> + </item> + <item> + <p> + Add function <c>enif_hash</c> for NIFs to calculate hash + values of arbitrary terms.</p> + <p> + Own Id: OTP-14385 Aux Id: PR-1413 </p> + </item> + <item> + <p>'<c>./configure --enable-lock-counter</c>' will + enabling building of an additional emulator that has + support for lock counting. (The option previously + existed, but would turn on lock counting in the default + emulator being built.) To start the lock-counting + emulator, use '<c>erl -emu_type lcnt</c>'.</p> + <p>On Windows, <c>erl</c> recognized the undocumented + option <c>-debug</c> for starting a debug-compiled + emulator. That option has been removed. Use '<c>erl + -emu_type debug</c>' instead.</p> + <p> + Own Id: OTP-14407</p> + </item> + <item> + <p> + Warnings have been added to the relevant documentation + about not using un-secure distributed nodes in exposed + environments.</p> + <p> + Own Id: OTP-14425</p> + </item> + <item> + <p> + Improvement of the documentation of the environment + variable <c>ERL_CRASH_DUMP_SECONDS</c> as well as the + default behavior when it is not set.</p> + <p> + Own Id: OTP-14434</p> + </item> + <item> + <p> + Enabled off-heap message queue for some system processes + that might receive large amounts of messages.</p> + <p> + Own Id: OTP-14438</p> + </item> + <item> + <p>ETS lock indexes have been replaced with the table + name in LCNT results.</p> + <p> + Own Id: OTP-14442 Aux Id: ERIERL-22 </p> + </item> + <item> + <p> + Introduced the new functions <seealso + marker="erl_nif#enif_whereis_pid"><c>enif_whereis_pid()</c></seealso> + and <seealso + marker="erl_nif#enif_whereis_port"><c>enif_whereis_port()</c></seealso>.</p> + <p> + Own Id: OTP-14453 Aux Id: PR-1400 </p> + </item> + </list> + </section> + +</section> + <section><title>Erts 8.3.5.7</title> <section><title>Fixed Bugs and Malfunctions</title> @@ -227,7 +3416,6 @@ </section> <section><title>Erts 8.3.5.1</title> - <section><title>Fixed Bugs and Malfunctions</title> <list> <item> @@ -1141,7 +4329,7 @@ <list> <item> <p> - Fixed a VM crash that occured in a garbage collection of + Fixed a VM crash that occurred in a garbage collection of a process when it had received binaries. This bug was introduced in ERTS version 8.0 (OTP 19.0).</p> <p> @@ -1158,7 +4346,7 @@ <list> <item> <p> - Fixed a VM crash that occured in garbage collection of a + Fixed a VM crash that occurred in garbage collection of a process when it had received maps over the distribution. This bug was introduced in ERTS version 8.0 (OTP 19.0).</p> <p> @@ -1969,6 +5157,179 @@ </section> +<section><title>Erts 7.3.1.6</title> + + <section><title>Improvements and New Features</title> + <list> + <item> + <p>List subtraction (The <c>--</c> operator) will now + yield properly on large inputs.</p> + <p> + Own Id: OTP-15371</p> + </item> + </list> + </section> + +</section> + +<section><title>Erts 7.3.1.5</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> + Fixed small memory leak that could occur when sending to + a terminating port.</p> + <p> + Own Id: OTP-14609 Aux Id: ERIERL-238 </p> + </item> + </list> + </section> + +</section> + +<section><title>Erts 7.3.1.4</title> + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> + Fix performance bug in pre-allocators that could cause + them to permanently fall back on normal more expensive + memory allocation. Pre-allocators are used for quick + allocation of short lived meta data used by messages and + other scheduled tasks. Bug exists since OTP_R15B02.</p> + <p> + Own Id: OTP-14491</p> + </item> + <item> + <p> + Fixed bug in operator <c>bxor</c> causing erroneuos + result when one operand is a big <em>negative</em> + integer with the lowest <c>N*W</c> bits as zero and the + other operand not larger than <c>N*W</c> bits. <c>N</c> + is an integer of 1 or larger and <c>W</c> is 32 or 64 + depending on word size.</p> + <p> + Own Id: OTP-14514</p> + </item> + <item> + <p> + A timer internal bit-field used for storing scheduler id + was too small. As a result, VM internal timer data + structures could become inconsistent when using 1024 + schedulers on the system. Note that systems with less + than 1024 schedulers are not effected by this bug.</p> + <p> + This bug was introduced in ERTS version 7.0 (OTP 18.0).</p> + <p> + Own Id: OTP-14548 Aux Id: OTP-11997, ERL-468 </p> + </item> + <item> + <p> + Fixed bug in <c>binary_to_term</c> and + <c>binary_to_atom</c> that could cause VM crash. + Typically happens when the last character of an UTF8 + string is in the range 128 to 255, but truncated to only + one byte. Bug exists in <c>binary_to_term</c> since ERTS + version 5.10.2 (OTP_R16B01) and <c>binary_to_atom</c> + since ERTS version 9.0 (OTP-20.0).</p> + <p> + Own Id: OTP-14590 Aux Id: ERL-474 </p> + </item> + </list> + </section> +</section> + +<section><title>Erts 7.3.1.3</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <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 Aux Id: ERL-94 </p> + </item> + <item> + <p> + Calls to <c>erl_drv_send_term()</c> or + <c>erl_drv_output_term()</c> from a non-scheduler thread + while the corresponding port was invalid caused the + emulator to enter an inconsistent state which eventually + caused an emulator crash.</p> + <p> + Own Id: OTP-13866</p> + </item> + <item> + <p>Driver and NIF operations accessing processes or ports + could cause an emulator crash when used from + non-scheduler threads. Those operations are:</p> <list> + <item><c>erl_drv_send_term()</c></item> + <item><c>driver_send_term()</c></item> + <item><c>erl_drv_output_term()</c></item> + <item><c>driver_output_term()</c></item> + <item><c>enif_send()</c></item> + <item><c>enif_port_command()</c></item> </list> + <p> + Own Id: OTP-13869</p> + </item> + <item> + <p> + Fix bug in <c>binary_to_term</c> for binaries created by + <c>term_to_binary </c> with option <c>compressed</c>. The + bug can cause <c>badarg</c> exception for a valid binary + when Erlang VM is linked against a <c>zlib</c> library of + version 1.2.9 or newer. Bug exists since OTP 17.0.</p> + <p> + Own Id: OTP-14159 Aux Id: ERL-340 </p> + </item> + </list> + </section> + +</section> + +<section><title>Erts 7.3.1.2</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> + Fixed a race that could cause a lost wakeup of a process + that timed out in a <c>receive ... after</c>. This bug + was introduced in ERTS version 7.0.</p> + <p> + Own Id: OTP-13798 Aux Id: OTP-11997 </p> + </item> + <item> + <p> + Fixed segfault after writing an erl crash dump.</p> + <p> + Own Id: OTP-13799</p> + </item> + </list> + </section> + +</section> + +<section><title>Erts 7.3.1.1</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> + Fix scheduler deadlock bug in <c>ets:update_counter/4</c> + when key is not found and inserting the default object + causes the table to grow.</p> + <p> + Own Id: OTP-13731 Aux Id: ERL-188 </p> + </item> + </list> + </section> + +</section> + <section><title>Erts 7.3.1</title> <section><title>Fixed Bugs and Malfunctions</title> @@ -2220,6 +5581,31 @@ </section> +<section><title>Erts 7.2.1.1</title> + + <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> + </list> + </section> + +</section> + <section><title>Erts 7.2.1</title> <section><title>Fixed Bugs and Malfunctions</title> @@ -2893,8 +6279,7 @@ <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> + command line argument: <c>+secio false</c></p> <p>Characteristics impact compared to previous default:</p> <list> <item>Lower latency and smoother management of externally triggered I/O operations.</item> @@ -3295,6 +6680,103 @@ </section> +<section><title>Erts 6.4.1.7</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <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> + Calls to <c>erl_drv_send_term()</c> or + <c>erl_drv_output_term()</c> from a non-scheduler thread + while the corresponding port was invalid caused the + emulator to enter an inconsistent state which eventually + caused an emulator crash.</p> + <p> + Own Id: OTP-13866</p> + </item> + <item> + <p>Driver and NIF operations accessing processes or ports + could cause an emulator crash when used from + non-scheduler threads. Those operations are:</p> <list> + <item><c>erl_drv_send_term()</c></item> + <item><c>driver_send_term()</c></item> + <item><c>erl_drv_output_term()</c></item> + <item><c>driver_output_term()</c></item> + <item><c>enif_send()</c></item> + <item><c>enif_port_command()</c></item> </list> + <p> + Own Id: OTP-13869</p> + </item> + <item> + <p> + Fix bug in <c>binary_to_term</c> for binaries created by + <c>term_to_binary </c> with option <c>compressed</c>. The + bug can cause <c>badarg</c> exception for a valid binary + when Erlang VM is linked against a <c>zlib</c> library of + version 1.2.9 or newer. Bug exists since OTP 17.0.</p> + <p> + Own Id: OTP-14159 Aux Id: ERL-340 </p> + </item> + <item> + <p> + Fixed bug in operator <c>bxor</c> causing erroneuos + result when one operand is a big <em>negative</em> + integer with the lowest <c>N*W</c> bits as zero and the + other operand not larger than <c>N*W</c> bits. <c>N</c> + is an integer of 1 or larger and <c>W</c> is 32 or 64 + depending on word size.</p> + <p> + Own Id: OTP-14514</p> + </item> + <item> + <p> + Fixed bug in <c>binary_to_term</c> and + <c>binary_to_atom</c> that could cause VM crash. + Typically happens when the last character of an UTF8 + string is in the range 128 to 255, but truncated to only + one byte. Bug exists in <c>binary_to_term</c> since ERTS + version 5.10.2 (OTP_R16B01) and <c>binary_to_atom</c> + since ERTS version 9.0 (OTP-20.0).</p> + <p> + Own Id: OTP-14590 Aux Id: ERL-474 </p> + </item> + </list> + </section> + +</section> + +<section><title>Erts 6.4.1.6</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <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> + </list> + </section> + +</section> + <section><title>Erts 6.4.1.5</title> <section><title>Fixed Bugs and Malfunctions</title> @@ -3675,8 +7157,7 @@ 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> + command line argument: <c>+secio true</c></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 @@ -6259,7 +9740,7 @@ dependent, so applications aiming to be portable should consider using <c>{ipv6_v6only,true}</c> when creating an <c>inet6</c> listening/destination socket, and if - neccesary also create an <c>inet</c> socket on the same + necessary also create an <c>inet</c> socket on the same port for IPv4 traffic. See the documentation.</p> <p> Own Id: OTP-8928 Aux Id: kunagi-193 [104] </p> @@ -6640,7 +10121,7 @@ This change of default value will reduce lock contention on ETS tables using the <c>read_concurrency</c> option at the expense of memory consumption when the amount of - schedulers and logical processors are beween 8 and 64. + schedulers and logical processors are between 8 and 64. For more information, see documentation of the <c>+rg</c> command line argument of <c>erl(1)</c>.</p> <p> @@ -7617,7 +11098,7 @@ <p> For the subsection about process_flag(save_calls, N) there's an unrelated paragraph about process priorities - which was copied from the preceeding subsection regarding + which was copied from the preceding subsection regarding process_flag(priority, Level). (Thanks to Filipe David Manana)</p> <p> @@ -8832,7 +12313,7 @@ <item> <p> Wx on MacOS X generated complains on stderr about certain - cocoa functions not beeing called from the "Main thread". + cocoa functions not being called from the "Main thread". This is now corrected.</p> <p> Own Id: OTP-9081</p> @@ -9670,7 +13151,7 @@ <c>update_cpu_info</c> will make the runtime system reread and update the internally stored CPU information. For more information see the documentation of <seealso - marker="erlang#update_cpu_info">erlang:system_info(update_cpu_info)</seealso>.</p> + marker="erlang#system_info_update_cpu_info">erlang:system_info(update_cpu_info)</seealso>.</p> <p> The CPU topology is now automatically detected on Windows systems with less than 33 logical processors. The runtime @@ -9823,7 +13304,7 @@ </item> <item> <p>The <c>empd</c> program could loop and consume 100% - CPU time if an unexpected error ocurred in + CPU time if an unexpected error occurred in <c>listen()</c> or <c>accept()</c>. Now <c>epmd</c> will terminate if a non-recoverable error occurs. (Thanks to Michael Santos.)</p> @@ -16122,4 +19603,3 @@ </section> </section> </chapter> - diff --git a/erts/doc/src/part.xml b/erts/doc/src/part.xml index d583b873a0..05e9a24af8 100644 --- a/erts/doc/src/part.xml +++ b/erts/doc/src/part.xml @@ -4,7 +4,7 @@ <part xmlns:xi="http://www.w3.org/2001/XInclude"> <header> <copyright> - <year>1996</year><year>2016</year> + <year>1996</year><year>2018</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -37,6 +37,7 @@ <xi:include href="match_spec.xml"/> <xi:include href="crash_dump.xml"/> <xi:include href="alt_dist.xml"/> + <xi:include href="alt_disco.xml"/> <xi:include href="absform.xml"/> <xi:include href="tty.xml"/> <xi:include href="driver.xml"/> diff --git a/erts/doc/src/part_notes.xml b/erts/doc/src/part_notes.xml deleted file mode 100644 index e579b7635d..0000000000 --- a/erts/doc/src/part_notes.xml +++ /dev/null @@ -1,38 +0,0 @@ -<?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>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>ERTS Release Notes</title> - <prepared></prepared> - <docno></docno> - <date>2004-09-07</date> - <rev>1.0</rev> - </header> - <description> - <p>The Erlang Runtime System application <em>ERTS</em>.</p> - <p>For information about older versions, see - <url href="part_notes_history_frame.html">Release Notes History</url>.</p> - </description> - <xi:include href="notes.xml"/> -</part> - diff --git a/erts/doc/src/part_notes_history.xml b/erts/doc/src/part_notes_history.xml deleted file mode 100644 index 277683a2b5..0000000000 --- a/erts/doc/src/part_notes_history.xml +++ /dev/null @@ -1,36 +0,0 @@ -<?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>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>ERTS Release Notes History</title> - <prepared></prepared> - <docno></docno> - <date></date> - <rev></rev> - </header> - <description> - <p>The Erlang Runtime System application <em>ERTS</em>.</p> - </description> - <xi:include href="notes_history.xml"/> -</part> - diff --git a/erts/doc/src/persistent_term.xml b/erts/doc/src/persistent_term.xml new file mode 100644 index 0000000000..1eda7f8d76 --- /dev/null +++ b/erts/doc/src/persistent_term.xml @@ -0,0 +1,290 @@ +<?xml version="1.0" encoding="utf-8" ?> +<!DOCTYPE erlref SYSTEM "erlref.dtd"> + +<erlref> + <header> + <copyright> + <year>2018</year><year>2018</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>persistent_term</title> + <prepared></prepared> + <docno></docno> + <date></date> + <rev></rev> + <file>persistent_term.xml</file> + </header> + <module since="OTP 21.2">persistent_term</module> + <modulesummary>Persistent terms.</modulesummary> + <description> + <p>This module is similar to <seealso + marker="stdlib:ets"><c>ets</c></seealso> in that it provides a + storage for Erlang terms that can be accessed in constant time, + but with the difference that <c>persistent_term</c> has been + highly optimized for reading terms at the expense of writing and + updating terms. When a persistent term is updated or deleted, a + global garbage collection pass is run to scan all processes for + the deleted term, and to copy it into each process that still uses + it. Therefore, <c>persistent_term</c> is suitable for storing + Erlang terms that are frequently accessed but never or + infrequently updated.</p> + + <warning><p>Persistent terms is an advanced feature and is not a + general replacement for ETS tables. Before using persistent terms, + make sure to fully understand the consequence to system + performance when updating or deleting persistent terms.</p></warning> + + <p>Term lookup (using <seealso + marker="#get/1"><c>get/1</c></seealso>), is done in constant time + and without taking any locks, and the term is <strong>not</strong> + copied to the heap (as is the case with terms stored in ETS + tables).</p> + + <p>Storing or updating a term (using <seealso + marker="#put/2"><c>put/2</c></seealso>) is proportional to the + number of already created persistent terms because the hash table + holding the keys will be copied. In addition, the term itself will + be copied.</p> + + <p>When a (complex) term is deleted (using <seealso + marker="#erase/1"><c>erase/1</c></seealso>) or replaced by another + (using <seealso marker="#put/2"><c>put/2</c></seealso>), a global + garbage collection is initiated. It works like this:</p> + + <list> + <item><p>All processes in the system will be scheduled to run a + scan of their heaps for the term that has been deleted. While + such scan is relatively light-weight, if there are many + processes, the system can become less responsive until all + process have scanned their heaps.</p></item> + + <item><p>If the deleted term (or any part of it) is still used + by a process, that process will do a major (fullsweep) garbage + collection and copy the term into the process. However, at most + two processes at a time will be scheduled to do that kind of + garbage collection.</p></item> + </list> + + <p>Deletion of atoms and other terms that fit in one machine word + is specially optimized to avoid doing a global GC. It is still not + recommended to update persistent terms with such values too + frequently because the hash table holding the keys is copied every + time a persistent term is updated.</p> + + <p>Some examples are suitable uses for persistent terms are:</p> + + <list> + <item><p>Storing of configuration data that must be easily + accessible by all processes.</p></item> + + <item><p>Storing of references for NIF resources.</p></item> + + <item><p>Storing of references for efficient counters.</p></item> + + <item><p>Storing an atom to indicate a logging level or whether debugging + is turned on.</p></item> + </list> + + </description> + + <section> + <title>Storing Huge Persistent Terms</title> + <p>The current implementation of persistent terms uses the literal + <seealso marker="erts_alloc">allocator</seealso> also used for + literals (constant terms) in BEAM code. By default, 1 GB of + virtual address space is reserved for literals in BEAM code and + persistent terms. The amount of virtual address space reserved for + literals can be changed by using the <seealso + marker="erts_alloc#MIscs"><c>+MIscs option</c></seealso> when + starting the emulator.</p> + + <p>Here is an example how the reserved virtual address space for literals + can be raised to 2 GB (2048 MB):</p> + + <pre> + erl +MIscs 2048</pre> + </section> + + <section> + <title>Warning For Many Persistent Terms</title> + <p>The runtime system will send a warning report to the + error logger if more than 20000 persistent terms have been + created. It will look like this:</p> + +<pre> +More than 20000 persistent terms have been created. +It is recommended to avoid creating an excessive number of +persistent terms, as creation and deletion of persistent terms +will be slower as the number of persistent terms increases.</pre> + </section> + + <section> + <title>Best Practices for Using Persistent Terms</title> + + <p>It is recommended to use keys like <c>?MODULE</c> or + <c>{?MODULE,SubKey}</c> to avoid name collisions.</p> + + <p>Prefer creating a few large persistent terms to creating many + small persistent terms. The execution time for storing a + persistent term is proportional to the number of already existing + terms.</p> + + <p>Updating a persistent term with the same value as it already + has is specially optimized to do nothing quickly; thus, there is + no need compare the old and new values and avoid calling + <seealso marker="#put/2"><c>put/2</c></seealso> if the values + are equal.</p> + + <p>When atoms or other terms that fit in one machine word are + deleted, no global GC is needed. Therefore, persistent terms that + have atoms as their values can be updated more frequently, but + note that updating such persistent terms is still much more + expensive than reading them.</p> + + <p>Updating or deleting a persistent term will trigger a global GC + if the term does not fit in one machine word. Processes will be + scheduled as usual, but all processes will be made runnable at + once, which will make the system less responsive until all process + have run and scanned their heaps for the deleted terms. One way to + minimize the effects on responsiveness could be to minimize the + number of processes on the node before updating or deleting a + persistent term. It would also be wise to avoid updating terms + when the system is at peak load.</p> + + <p>Avoid storing a retrieved persistent term in a process if that + persistent term could be deleted or updated in the future. If a + process holds a reference to a persistent term when the term is + deleted, the process will be garbage collected and the term copied + to process.</p> + + <p>Avoid updating or deleting more than one persistent term at a + time. Each deleted term will trigger its own global GC. That + means that deleting N terms will make the system less responsive N + times longer than deleting a single persistent term. Therefore, + terms that are to be updated at the same time should be collected + into a larger term, for example, a map or a tuple.</p> + </section> + + <section> + <title>Example</title> + + <p>The following example shows how lock contention for ETS tables + can be minimized by having one ETS table for each scheduler. The + table identifiers for the ETS tables are stored as a single + persistent term:</p> + +<pre> + %% There is one ETS table for each scheduler. + Sid = erlang:system_info(scheduler_id), + Tid = element(Sid, persistent_term:get(?MODULE)), + ets:update_counter(Tid, Key, 1).</pre> + + </section> + + <datatypes> + <datatype> + <name name="key"/> + <desc> + <p>Any Erlang term.</p> + </desc> + </datatype> + <datatype> + <name name="value"/> + <desc> + <p>Any Erlang term.</p> + </desc> + </datatype> + </datatypes> + + <funcs> + <func> + <name name="erase" arity="1" since="OTP 21.2"/> + <fsummary>Erase the name for a persistent term.</fsummary> + <desc> + <p>Erase the name for the persistent term with key + <c><anno>Key</anno></c>. The return value will be <c>true</c> + if there was a persistent term with the key + <c><anno>Key</anno></c>, and <c>false</c> if there was no + persistent term associated with the key.</p> + <p>If there existed a previous persistent term associated with + key <c><anno>Key</anno></c>, a global GC has been initiated + when <c>erase/1</c> returns. See <seealso + marker="#description">Description</seealso>.</p> + </desc> + </func> + + <func> + <name name="get" arity="0" since="OTP 21.2"/> + <fsummary>Get all persistent terms.</fsummary> + <desc> + <p>Retrieve the keys and values for all persistent terms. + The keys will be copied to the heap for the process calling + <c>get/0</c>, but the values will not.</p> + </desc> + </func> + + <func> + <name name="get" arity="1" since="OTP 21.2"/> + <fsummary>Get the value for a persistent term.</fsummary> + <desc> + <p>Retrieve the value for the persistent term associated with + the key <c><anno>Key</anno></c>. The lookup will be made in + constant time and the value will not be copied to the heap + of the calling process.</p> + <p>This function fails with a <c>badarg</c> exception if no + term has been stored with the key + <c><anno>Key</anno></c>.</p> + <p>If the calling process holds on to the value of the + persistent term and the persistent term is deleted in the future, + the term will be copied to the process.</p> + </desc> + </func> + + <func> + <name name="info" arity="0" since="OTP 21.2"/> + <fsummary>Get information about persistent terms.</fsummary> + <desc> + <p>Return information about persistent terms in a map. The map + has the following keys:</p> + <taglist> + <tag><c>count</c></tag> + <item><p>The number of persistent terms.</p></item> + <tag><c>memory</c></tag> + <item><p>The total amount of memory (measured in bytes) + used by all persistent terms.</p></item> + </taglist> + </desc> + </func> + + <func> + <name name="put" arity="2" since="OTP 21.2"/> + <fsummary>Store a term.</fsummary> + <desc> + <p>Store the value <c><anno>Value</anno></c> as a persistent term and + associate it with the key <c><anno>Key</anno></c>.</p> + <p>If the value <c><anno>Value</anno></c> is equal to the value + previously stored for the key, <c>put/2</c> will do nothing and return + quickly.</p> + <p>If there existed a previous persistent term associated with + key <c><anno>Key</anno></c>, a global GC has been initiated + when <c>put/2</c> returns. See <seealso + marker="#description">Description</seealso>.</p> + </desc> + </func> + </funcs> +</erlref> diff --git a/erts/doc/src/ref_man.xml b/erts/doc/src/ref_man.xml index 0617463a7b..a78aaa449e 100644 --- a/erts/doc/src/ref_man.xml +++ b/erts/doc/src/ref_man.xml @@ -34,6 +34,7 @@ <xi:include href="erl_prim_loader.xml"/> <xi:include href="erlang.xml"/> <xi:include href="init.xml"/> + <xi:include href="persistent_term.xml"/> <xi:include href="zlib.xml"/> <xi:include href="epmd.xml"/> <xi:include href="erl.xml"/> @@ -49,5 +50,7 @@ <xi:include href="erts_alloc.xml"/> <xi:include href="erl_nif.xml"/> <xi:include href="erl_tracer.xml"/> + <xi:include href="atomics.xml"/> + <xi:include href="counters.xml"/> </application> diff --git a/erts/doc/src/run_erl.xml b/erts/doc/src/run_erl.xml index a9b6a7e2c6..fa36457489 100644 --- a/erts/doc/src/run_erl.xml +++ b/erts/doc/src/run_erl.xml @@ -4,7 +4,7 @@ <comref> <header> <copyright> - <year>1999</year><year>2016</year> + <year>1999</year><year>2018</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -181,6 +181,12 @@ <item> <p>Controls the number of log files written before older files are reused. Defaults to 5, minimum is 2, maximum is 1000.</p> + <p>Note that, as a way to indicate the newest file, <c>run_erl</c> will + delete the oldest log file to maintain a "hole" in the file + sequences. For example, if log files #1, #2, #4 and #5 exists, that + means #2 is the latest and #4 is the oldest. You will therefore at most + get one less log file than the value set by + <c>RUN_ERL_LOG_GENERATIONS</c>.</p> </item> <tag><c>RUN_ERL_LOG_MAXSIZE</c></tag> <item> diff --git a/erts/doc/src/specs.xml b/erts/doc/src/specs.xml index ed6be650e5..0b943e6295 100644 --- a/erts/doc/src/specs.xml +++ b/erts/doc/src/specs.xml @@ -4,5 +4,8 @@ <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_persistent_term.xml"/> <xi:include href="../specs/specs_zlib.xml"/> + <xi:include href="../specs/specs_atomics.xml"/> + <xi:include href="../specs/specs_counters.xml"/> </specs> diff --git a/erts/doc/src/time_correction.xml b/erts/doc/src/time_correction.xml index 77e7a40529..a9f06d8a7d 100644 --- a/erts/doc/src/time_correction.xml +++ b/erts/doc/src/time_correction.xml @@ -4,7 +4,7 @@ <chapter> <header> <copyright> - <year>1999</year><year>2016</year> + <year>1999</year><year>2018</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -940,7 +940,7 @@ EventTag = {Time, UMI}</code> </item> <item> <seealso marker="erlang#system_info_os_system_time_source"> - <c>erlang:system_info(os_system_time_source)</c></seealso>) + <c>erlang:system_info(os_system_time_source)</c></seealso> </item> </list> diff --git a/erts/doc/src/zlib.xml b/erts/doc/src/zlib.xml index f8140544b7..38229456c9 100644 --- a/erts/doc/src/zlib.xml +++ b/erts/doc/src/zlib.xml @@ -29,7 +29,7 @@ <rev></rev> <file>zlib.xml</file> </header> - <module>zlib</module> + <module since="">zlib</module> <modulesummary>zlib compression interface.</modulesummary> <description> <p>This module provides an API for the zlib library @@ -65,13 +65,22 @@ list_to_binary([Compressed|Last])</pre> <tag><c>badarg</c></tag> <item>Bad argument. </item> + <tag><c>not_initialized</c></tag> + <item>The stream hasn't been initialized, eg. if + <seealso marker="#inflateInit/1"><c>inflateInit/1</c></seealso> wasn't + called prior to a call to + <seealso marker="#inflate/2"><c>inflate/2</c></seealso>. + </item> + <tag><c>not_on_controlling_process</c></tag> + <item>The stream was used by a process that doesn't control it. Use + <seealso marker="#set_controlling_process/2"> + <c>set_controlling_process/2</c></seealso> if you need to transfer + a stream to a different process.</item> <tag><c>data_error</c></tag> <item>The data contains errors. </item> <tag><c>stream_error</c></tag> <item>Inconsistent stream state.</item> - <tag><c>einval</c></tag> - <item>Bad value or wrong function called.</item> <tag><c>{need_dictionary,Adler32}</c></tag> <item>See <seealso marker="#inflate/2"><c>inflate/2</c></seealso>. </item> @@ -90,6 +99,9 @@ list_to_binary([Compressed|Last])</pre> <name name="zlevel"/> </datatype> <datatype> + <name name="zflush"/> + </datatype> + <datatype> <name name="zmemlevel"/> </datatype> <datatype> @@ -108,15 +120,20 @@ list_to_binary([Compressed|Last])</pre> <funcs> <func> - <name name="adler32" arity="2"/> + <name name="adler32" arity="2" since=""/> <fsummary>Calculate the Adler checksum.</fsummary> <desc> <p>Calculates the Adler-32 checksum for <c><anno>Data</anno></c>.</p> + <warning> + <p>This function is deprecated and will be removed in a future + release. Use <seealso marker="erts:erlang#adler32/1"> + <c>erlang:adler32/1</c></seealso> instead.</p> + </warning> </desc> </func> <func> - <name name="adler32" arity="3"/> + <name name="adler32" arity="3" since=""/> <fsummary>Calculate the Adler checksum.</fsummary> <desc> <p>Updates a running Adler-32 checksum for <c><anno>Data</anno></c>. @@ -127,11 +144,16 @@ list_to_binary([Compressed|Last])</pre> Crc = lists:foldl(fun(Data,Crc0) -> zlib:adler32(Z, Crc0, Data), end, zlib:adler32(Z,<< >>), Datas)</pre> + <warning> + <p>This function is deprecated and will be removed in a future + release. Use <seealso marker="erts:erlang#adler32/2"> + <c>erlang:adler32/2</c></seealso> instead.</p> + </warning> </desc> </func> <func> - <name name="adler32_combine" arity="4"/> + <name name="adler32_combine" arity="4" since=""/> <fsummary>Combine two Adler-32 checksums.</fsummary> <desc> <p>Combines two Adler-32 checksums into one. For two binaries or @@ -141,11 +163,16 @@ Crc = lists:foldl(fun(Data,Crc0) -> <p>This function returns the <c><anno>Adler</anno></c> checksum of <c>[Data1,Data2]</c>, requiring only <c><anno>Adler1</anno></c>, <c><anno>Adler2</anno></c>, and <c><anno>Size2</anno></c>.</p> + <warning> + <p>This function is deprecated and will be removed in a future + release. Use <seealso marker="erts:erlang#adler32_combine/3"> + <c>erlang:adler32_combine/3</c></seealso> instead.</p> + </warning> </desc> </func> <func> - <name name="close" arity="1"/> + <name name="close" arity="1" since=""/> <fsummary>Close a stream.</fsummary> <desc> <p>Closes the stream referenced by <c><anno>Z</anno></c>.</p> @@ -153,7 +180,7 @@ Crc = lists:foldl(fun(Data,Crc0) -> </func> <func> - <name name="compress" arity="1"/> + <name name="compress" arity="1" since=""/> <fsummary>Compress data with standard zlib functionality.</fsummary> <desc> <p>Compresses data with zlib headers and checksum.</p> @@ -161,23 +188,34 @@ Crc = lists:foldl(fun(Data,Crc0) -> </func> <func> - <name name="crc32" arity="1"/> + <name name="crc32" arity="1" since=""/> <fsummary>Get current CRC.</fsummary> <desc> <p>Gets the current calculated CRC checksum.</p> + <warning> + <p>This function is deprecated and will be removed in a future + release. Use <seealso marker="erts:erlang#crc32/1"> + <c>erlang:crc32/1</c></seealso> on the uncompressed data + instead.</p> + </warning> </desc> </func> <func> - <name name="crc32" arity="2"/> + <name name="crc32" arity="2" since=""/> <fsummary>Calculate CRC.</fsummary> <desc> <p>Calculates the CRC checksum for <c><anno>Data</anno></c>.</p> + <warning> + <p>This function is deprecated and will be removed in a future + release. Use <seealso marker="erts:erlang#crc32/1"> + <c>erlang:crc32/1</c></seealso> instead.</p> + </warning> </desc> </func> <func> - <name name="crc32" arity="3"/> + <name name="crc32" arity="3" since=""/> <fsummary>Calculate CRC.</fsummary> <desc> <p>Updates a running CRC checksum for <c><anno>Data</anno></c>. @@ -188,11 +226,16 @@ Crc = lists:foldl(fun(Data,Crc0) -> Crc = lists:foldl(fun(Data,Crc0) -> zlib:crc32(Z, Crc0, Data), end, zlib:crc32(Z,<< >>), Datas)</pre> + <warning> + <p>This function is deprecated and will be removed in a future + release. Use <seealso marker="erts:erlang#crc32/2"> + <c>erlang:crc32/2</c></seealso> instead.</p> + </warning> </desc> </func> <func> - <name name="crc32_combine" arity="4"/> + <name name="crc32_combine" arity="4" since=""/> <fsummary>Combine two CRCs.</fsummary> <desc> <p>Combines two CRC checksums into one. For two binaries or iolists, @@ -202,11 +245,16 @@ Crc = lists:foldl(fun(Data,Crc0) -> <p>This function returns the <c><anno>CRC</anno></c> checksum of <c>[Data1,Data2]</c>, requiring only <c><anno>CRC1</anno></c>, <c><anno>CRC2</anno></c>, and <c><anno>Size2</anno></c>.</p> + <warning> + <p>This function is deprecated and will be removed in a future + release. Use <seealso marker="erts:erlang#crc32_combine/3"> + <c>erlang:crc32_combine/3</c></seealso> instead.</p> + </warning> </desc> </func> <func> - <name name="deflate" arity="2"/> + <name name="deflate" arity="2" since=""/> <fsummary>Compress data.</fsummary> <desc> <p>Same as <c>deflate(<anno>Z</anno>, <anno>Data</anno>, none)</c>.</p> @@ -214,7 +262,7 @@ Crc = lists:foldl(fun(Data,Crc0) -> </func> <func> - <name name="deflate" arity="3"/> + <name name="deflate" arity="3" since=""/> <fsummary>Compress data.</fsummary> <desc> <p>Compresses as much data as possible, and @@ -252,7 +300,7 @@ list_to_binary([B1,B2])</pre> </func> <func> - <name name="deflateEnd" arity="1"/> + <name name="deflateEnd" arity="1" since=""/> <fsummary>End deflate session.</fsummary> <desc> <p>Ends the deflate session and cleans all data used. Notice that this @@ -263,7 +311,7 @@ list_to_binary([B1,B2])</pre> </func> <func> - <name name="deflateInit" arity="1"/> + <name name="deflateInit" arity="1" since=""/> <fsummary>Initialize a session for compression.</fsummary> <desc> <p>Same as <c>zlib:deflateInit(<anno>Z</anno>, default)</c>.</p> @@ -271,7 +319,7 @@ list_to_binary([B1,B2])</pre> </func> <func> - <name name="deflateInit" arity="2"/> + <name name="deflateInit" arity="2" since=""/> <fsummary>Initialize a session for compression.</fsummary> <desc> <p>Initializes a zlib stream for compression.</p> @@ -286,7 +334,7 @@ list_to_binary([B1,B2])</pre> </func> <func> - <name name="deflateInit" arity="6"/> + <name name="deflateInit" arity="6" since=""/> <fsummary>Initialize a session for compression.</fsummary> <desc> <p>Initiates a zlib stream for compression.</p> @@ -362,7 +410,7 @@ list_to_binary([B1,B2])</pre> </func> <func> - <name name="deflateParams" arity="3"/> + <name name="deflateParams" arity="3" since=""/> <fsummary>Dynamicly update deflate parameters.</fsummary> <desc> <p>Dynamically updates the compression level and compression @@ -384,7 +432,7 @@ list_to_binary([B1,B2])</pre> </func> <func> - <name name="deflateReset" arity="1"/> + <name name="deflateReset" arity="1" since=""/> <fsummary>Reset the deflate session.</fsummary> <desc> <p>Equivalent to @@ -398,7 +446,7 @@ list_to_binary([B1,B2])</pre> </func> <func> - <name name="deflateSetDictionary" arity="2"/> + <name name="deflateSetDictionary" arity="2" since=""/> <fsummary>Initialize the compression dictionary.</fsummary> <desc> <p>Initializes the compression dictionary from the specified byte @@ -407,8 +455,8 @@ list_to_binary([B1,B2])</pre> <seealso marker="#deflateInit/1"><c>deflateInit/1,2,6</c></seealso> or <seealso marker="#deflateReset/1"><c>deflateReset/1</c></seealso>, before any call of - <seealso marker="#deflate/3"><c>deflate/3</c></seealso>. - The compressor and decompressor must use the same dictionary (see + <seealso marker="#deflate/3"><c>deflate/3</c></seealso>.</p> + <p>The compressor and decompressor must use the same dictionary (see <seealso marker="#inflateSetDictionary/2"> <c>inflateSetDictionary/2</c></seealso>).</p> <p>The Adler checksum of the dictionary is returned.</p> @@ -416,15 +464,19 @@ list_to_binary([B1,B2])</pre> </func> <func> - <name name="getBufSize" arity="1"/> + <name name="getBufSize" arity="1" since=""/> <fsummary>Get buffer size.</fsummary> <desc> <p>Gets the size of the intermediate buffer.</p> + <warning> + <p>This function is deprecated and will be removed in a future + release.</p> + </warning> </desc> </func> <func> - <name name="gunzip" arity="1"/> + <name name="gunzip" arity="1" since=""/> <fsummary>Uncompress data with gz header.</fsummary> <desc> <p>Uncompresses data with gz headers and checksum.</p> @@ -432,7 +484,7 @@ list_to_binary([B1,B2])</pre> </func> <func> - <name name="gzip" arity="1"/> + <name name="gzip" arity="1" since=""/> <fsummary>Compress data with gz header.</fsummary> <desc> <p>Compresses data with gz headers and checksum.</p> @@ -440,24 +492,46 @@ list_to_binary([B1,B2])</pre> </func> <func> - <name name="inflate" arity="2"/> + <name name="inflate" arity="2" since=""/> <fsummary>Decompress data.</fsummary> <desc> - <p>Decompresses as much data as possible. - It can introduce some output latency (reading - input without producing any output).</p> - <p>If a preset dictionary is needed at this point (see - <seealso marker="#inflateSetDictionary/2"> - <c>inflateSetDictionary/2</c></seealso>), <c>inflate/2</c> throws a - <c>{need_dictionary,Adler}</c> exception, where <c>Adler</c> is - the Adler-32 checksum of the dictionary chosen by the compressor.</p> + <p>Equivalent to + <seealso marker="#inflate/3"><c>inflate(Z, Data, [])</c></seealso> + </p> </desc> </func> <func> - <name name="inflateChunk" arity="1"/> + <name name="inflate" arity="3" since="OTP 20.1"/> + <fsummary>Decompress data.</fsummary> + <desc> + <p>Decompresses as much data as possible. It can introduce some output + latency (reading input without producing any output).</p> + <p>Currently the only available option is + <c>{exception_on_need_dict,boolean()}</c> which controls whether the + function should throw an exception when a preset dictionary is + required for decompression. When set to false, a + <c>need_dictionary</c> tuple will be returned instead. See + <seealso marker="#inflateSetDictionary/2"> + <c>inflateSetDictionary/2</c></seealso> for details.</p> + <warning> + <p>This option defaults to <c>true</c> for backwards compatibility + but we intend to remove the exception behavior in a future + release. New code that needs to handle dictionaries manually + should always specify <c>{exception_on_need_dict,false}</c>.</p> + </warning> + </desc> + </func> + + <func> + <name name="inflateChunk" arity="1" since="OTP 18.0"/> <fsummary>Read next uncompressed chunk.</fsummary> <desc> + <warning> + <p>This function is deprecated and will be removed in a future + release. Use <seealso marker="#safeInflate/2"><c>safeInflate/2</c> + </seealso> instead.</p> + </warning> <p>Reads the next chunk of uncompressed data, initialized by <seealso marker="#inflateChunk/2"><c>inflateChunk/2</c></seealso>.</p> <p>This function is to be repeatedly called, while it returns @@ -466,26 +540,30 @@ list_to_binary([B1,B2])</pre> </func> <func> - <name name="inflateChunk" arity="2"/> + <name name="inflateChunk" arity="2" since="OTP 18.0"/> <fsummary>Decompress data with limited output size.</fsummary> <desc> + <warning> + <p>This function is deprecated and will be removed in a future + release. Use <seealso marker="#safeInflate/2"><c>safeInflate/2</c> + </seealso> instead.</p> + </warning> <p>Like <seealso marker="#inflate/2"><c>inflate/2</c></seealso>, - but decompresses no more data than will fit in the buffer configured - through <seealso marker="#setBufSize/2"><c>setBufSize/2</c></seealso>. - Is is useful when decompressing a stream with a high compression - ratio, such that a small amount of compressed input can expand up to - 1000 times.</p> + but decompresses no more data than will fit in the buffer configured + through <seealso marker="#setBufSize/2"><c>setBufSize/2</c> + </seealso>. Is is useful when decompressing a stream with a high + compression ratio, such that a small amount of compressed input can + expand up to 1000 times.</p> <p>This function returns <c>{more, Decompressed}</c>, when there is - more output available, and - <seealso marker="#inflateChunk/1"><c>inflateChunk/1</c></seealso> - is to be used to read it.</p> - <p>This function can introduce some output latency (reading - input without producing any output).</p> - <p>If a preset dictionary is needed at this point (see - <seealso marker="#inflateSetDictionary/2"> - <c>inflateSetDictionary/2</c></seealso>), this function throws a - <c>{need_dictionary,Adler}</c> exception, where <c>Adler</c> is - the Adler-32 checksum of the dictionary chosen by the compressor.</p> + more output available, and + <seealso marker="#inflateChunk/1"><c>inflateChunk/1</c></seealso> + is to be used to read it.</p> + <p>This function can introduce some output latency (reading input + without producing any output).</p> + <p>An exception will be thrown if a preset dictionary is required for + further decompression. See + <seealso marker="#inflateSetDictionary/2"> + <c>inflateSetDictionary/2</c></seealso> for details.</p> <p>Example:</p> <pre> walk(Compressed, Handler) -> @@ -506,7 +584,7 @@ loop(Z, Handler, Uncompressed) -> </func> <func> - <name name="inflateEnd" arity="1"/> + <name name="inflateEnd" arity="1" since=""/> <fsummary>End inflate session.</fsummary> <desc> <p>Ends the inflate session and cleans all data used. Notice @@ -517,7 +595,19 @@ loop(Z, Handler, Uncompressed) -> </func> <func> - <name name="inflateInit" arity="1"/> + <name name="inflateGetDictionary" arity="1" since="OTP 20.0"/> + <fsummary>Return the decompression dictionary.</fsummary> + <desc> + <p>Returns the decompression dictionary currently in use + by the stream. This function must be called between + <seealso marker="#inflateInit/1"><c>inflateInit/1,2</c></seealso> + and <seealso marker="#inflateEnd/1"><c>inflateEnd</c></seealso>.</p> + <p>Only supported if ERTS was compiled with zlib >= 1.2.8.</p> + </desc> + </func> + + <func> + <name name="inflateInit" arity="1" since=""/> <fsummary>Initialize a session for decompression.</fsummary> <desc> <p>Initializes a zlib stream for decompression.</p> @@ -525,7 +615,7 @@ loop(Z, Handler, Uncompressed) -> </func> <func> - <name name="inflateInit" arity="2"/> + <name name="inflateInit" arity="2" since=""/> <fsummary>Initialize a session for decompression.</fsummary> <desc> <p>Initializes a decompression session on zlib stream.</p> @@ -544,7 +634,7 @@ loop(Z, Handler, Uncompressed) -> </func> <func> - <name name="inflateReset" arity="1"/> + <name name="inflateReset" arity="1" since=""/> <fsummary>>Reset the inflate session.</fsummary> <desc> <p>Equivalent to @@ -558,34 +648,47 @@ loop(Z, Handler, Uncompressed) -> </func> <func> - <name name="inflateSetDictionary" arity="2"/> + <name name="inflateSetDictionary" arity="2" since=""/> <fsummary>Initialize the decompression dictionary.</fsummary> <desc> <p>Initializes the decompression dictionary from the specified - uncompressed byte sequence. This function must be called - immediately after a call of - <seealso marker="#inflate/2"><c>inflate/2</c></seealso> - if this call threw a <c>{need_dictionary,Adler}</c> exception. - The dictionary chosen by the compressor can be determined from the - Adler value thrown by the call to <c>inflate/2</c>. - The compressor and decompressor must use the same dictionary (see - <seealso marker="#deflateSetDictionary/2"> - <c>deflateSetDictionary/2</c></seealso>).</p> + uncompressed byte sequence. This function must be called as a + response to an inflate operation (eg. + <seealso marker="#safeInflate/2"><c>safeInflate/2</c></seealso>) + returning <c>{need_dictionary,Adler,Output}</c> or in the case of + deprecated functions, throwing an + <c>{'EXIT',{{need_dictionary,Adler},_StackTrace}}</c> exception.</p> + <p>The dictionary chosen by the compressor can be determined from the + Adler value returned or thrown by the call to the inflate function. + The compressor and decompressor must use the same dictionary (See + <seealso marker="#deflateSetDictionary/2"> + <c>deflateSetDictionary/2</c></seealso>).</p> + <p>After setting the dictionary the inflate operation should be + retried without new input.</p> <p>Example:</p> <pre> -unpack(Z, Compressed, Dict) -> +deprecated_unpack(Z, Compressed, Dict) -> case catch zlib:inflate(Z, Compressed) of - {'EXIT',{{need_dictionary,DictID},_}} -> - zlib:inflateSetDictionary(Z, Dict), + {'EXIT',{{need_dictionary,_DictID},_}} -> + ok = zlib:inflateSetDictionary(Z, Dict), Uncompressed = zlib:inflate(Z, []); Uncompressed -> Uncompressed - end.</pre> + end. + +new_unpack(Z, Compressed, Dict) -> + case zlib:inflate(Z, Compressed, [{exception_on_need_dict, false}]) of + {need_dictionary, _DictId, Output} -> + ok = zlib:inflateSetDictionary(Z, Dict), + [Output | zlib:inflate(Z, [])]; + Uncompressed -> + Uncompressed + end.</pre> </desc> </func> <func> - <name name="open" arity="0"/> + <name name="open" arity="0" since=""/> <fsummary>Open a stream and return a stream reference.</fsummary> <desc> <p>Opens a zlib stream.</p> @@ -593,15 +696,65 @@ unpack(Z, Compressed, Dict) -> </func> <func> - <name name="setBufSize" arity="2"/> + <name name="safeInflate" arity="2" since="OTP 20.1"/> + <fsummary>Decompress data with limited output size.</fsummary> + <desc> + <p>Like <seealso marker="#inflate/2"><c>inflate/2</c></seealso>, + but returns once it has expanded beyond a small + implementation-defined threshold. It's useful when decompressing + untrusted input which could have been maliciously crafted to expand + until the system runs out of memory.</p> + <p>This function returns <c>{continue | finished, Output}</c>, where + <anno>Output</anno> is the data that was decompressed in this call. + New input can be queued up on each call if desired, and the function + will return <c>{finished, Output}</c> once all queued data has been + decompressed.</p> + <p>This function can introduce some output latency (reading + input without producing any output).</p> + <p>If a preset dictionary is required for further decompression, this + function returns a <c>need_dictionary</c> tuple. See + <seealso marker="#inflateSetDictionary/2"> + <c>inflateSetDictionary/2</c></seealso>) for details.</p> + <p>Example:</p> + <pre> +walk(Compressed, Handler) -> + Z = zlib:open(), + zlib:inflateInit(Z), + loop(Z, Handler, zlib:safeInflate(Z, Compressed)), + zlib:inflateEnd(Z), + zlib:close(Z). + +loop(Z, Handler, {continue, Output}) -> + Handler(Output), + loop(Z, Handler, zlib:safeInflate(Z, [])); +loop(Z, Handler, {finished, Output}) -> + Handler(Output).</pre> + </desc> + </func> + + <func> + <name name="setBufSize" arity="2" since=""/> <fsummary>Set buffer size.</fsummary> <desc> <p>Sets the intermediate buffer size.</p> + <warning> + <p>This function is deprecated and will be removed in a future + release.</p> + </warning> + </desc> + </func> + + <func> + <name name="set_controlling_process" arity="2" since="OTP 20.1.3"/> + <fsummary>Transfers ownership of a zlib stream.</fsummary> + <desc> + <p>Changes the controlling process of <c><anno>Z</anno></c> to + <c><anno>Pid</anno></c>, which must be a local process.</p> </desc> </func> <func> - <name name="uncompress" arity="1"/> + <name name="uncompress" arity="1" since=""/> <fsummary>Uncompress data with standard zlib functionality.</fsummary> <desc> <p>Uncompresses data with zlib headers and checksum.</p> @@ -609,7 +762,7 @@ unpack(Z, Compressed, Dict) -> </func> <func> - <name name="unzip" arity="1"/> + <name name="unzip" arity="1" since=""/> <fsummary>Uncompress data without the zlib headers.</fsummary> <desc> <p>Uncompresses data without zlib headers and checksum.</p> @@ -617,7 +770,7 @@ unpack(Z, Compressed, Dict) -> </func> <func> - <name name="zip" arity="1"/> + <name name="zip" arity="1" since=""/> <fsummary>Compress data without the zlib headers.</fsummary> <desc> <p>Compresses data without zlib headers and checksum.</p> |