diff options
Diffstat (limited to 'erts/doc')
38 files changed, 3823 insertions, 375 deletions
diff --git a/erts/doc/src/Makefile b/erts/doc/src/Makefile index 89d7c85a86..e8b856c3ff 100644 --- a/erts/doc/src/Makefile +++ b/erts/doc/src/Makefile @@ -78,6 +78,7 @@ XML_CHAPTER_FILES = \ erl_ext_dist.xml \ erl_dist_protocol.xml \ communication.xml \ + time_correction.xml \ notes.xml \ notes_history.xml @@ -138,7 +139,7 @@ man: $(MAN1_FILES) $(MAN3_FILES) gifs: $(GIF_FILES:%=$(HTMLDIR)/%) -$(INFO_FILE): $(INFO_FILE_SRC) ../../vsn.mk +$(INFO_FILE): $(INFO_FILE_SRC) $(ERL_TOP)/make/$(TARGET)/otp.mk sed -e 's;%RELEASE%;$(SYSTEM_VSN);' $(INFO_FILE_SRC) > $(INFO_FILE) diff --git a/erts/doc/src/absform.xml b/erts/doc/src/absform.xml index e512c19e05..835a4fc692 100644 --- a/erts/doc/src/absform.xml +++ b/erts/doc/src/absform.xml @@ -1,4 +1,4 @@ -<?xml version="1.0" encoding="latin1" ?> +<?xml version="1.0" encoding="utf-8" ?> <!DOCTYPE chapter SYSTEM "chapter.dtd"> <chapter> @@ -217,6 +217,14 @@ Rep(E) = <c><![CDATA[{record_index,LINE,Name,Rep(Field)}]]></c>.</item> <item>If E is <c><![CDATA[E_0#Name.Field]]></c>, then Rep(E) = <c><![CDATA[{record_field,LINE,Rep(E_0),Name,Rep(Field)}]]></c>.</item> + <item>If E is <c><![CDATA[#{W_1, ..., W_k}]]></c> where each + <c><![CDATA[W_i]]></c> is a map assoc or exact field, then Rep(E) = + <c><![CDATA[{map,LINE,[Rep(W_1), ..., Rep(W_k)]}]]></c>. For Rep(W), see + below.</item> + <item>If E is <c><![CDATA[E_0#{W_1, ..., W_k}]]></c> where + <c><![CDATA[W_i]]></c> is a map assoc or exact field, then Rep(E) = + <c><![CDATA[{map,LINE,Rep(E_0),[Rep(W_1), ..., Rep(W_k)]}]]></c>. For + Rep(W), see below.</item> <item>If E is <c><![CDATA[catch E_0]]></c>, then Rep(E) = <c><![CDATA[{'catch',LINE,Rep(E_0)}]]></c>.</item> <item>If E is <c><![CDATA[E_0(E_1, ..., E_k)]]></c>, then @@ -290,6 +298,18 @@ <item>If E is <c><![CDATA[fun Fc_1 ; ... ; Fc_k end]]></c> where each <c><![CDATA[Fc_i]]></c> is a function clause then Rep(E) = <c><![CDATA[{'fun',LINE,{clauses,[Rep(Fc_1), ..., Rep(Fc_k)]}}]]></c>.</item> + <item>If E is <c><![CDATA[fun Name Fc_1 ; ... ; Name Fc_k end]]></c> + where <c><![CDATA[Name]]></c> is a variable and each + <c><![CDATA[Fc_i]]></c> is a function clause then Rep(E) = + <c><![CDATA[{named_fun,LINE,Name,[Rep(Fc_1), ..., Rep(Fc_k)]}]]></c>. + </item> + <item>If E is <c><![CDATA[query [E_0 || W_1, ..., W_k] end]]></c>, + where each <c><![CDATA[W_i]]></c> is a generator or a filter, then + Rep(E) = <c><![CDATA[{'query',LINE,{lc,LINE,Rep(E_0),[Rep(W_1), ..., Rep(W_k)]}}]]></c>. + For Rep(W), see below.</item> + <item>If E is <c><![CDATA[E_0.Field]]></c>, a Mnesia record access + inside a query, then + Rep(E) = <c><![CDATA[{record_field,LINE,Rep(E_0),Rep(Field)}]]></c>.</item> <item>If E is <c><![CDATA[( E_0 )]]></c>, then Rep(E) = <c><![CDATA[Rep(E_0)]]></c>, i.e., parenthesized expressions cannot be distinguished from their bodies.</item> @@ -322,6 +342,21 @@ is an integer, Rep(TS) = <c><![CDATA[{A, Value}]]></c>.</item> </list> </section> + + <section> + <title>Map assoc and exact fields</title> + <p>When W is an assoc or exact field (in the body of a map), then:</p> + <list type="bulleted"> + <item>If W is an assoc field <c><![CDATA[K => V]]></c>, where + <c><![CDATA[K]]></c> and <c><![CDATA[V]]></c> are both expressions, + then Rep(W) = <c><![CDATA[{map_field_assoc,LINE,Rep(K),Rep(V)}]]></c>. + </item> + <item>If W is an exact field <c><![CDATA[K := V]]></c>, where + <c><![CDATA[K]]></c> and <c><![CDATA[V]]></c> are both expressions, + then Rep(W) = <c><![CDATA[{map_field_exact,LINE,Rep(K),Rep(V)}]]></c>. + </item> + </list> + </section> </section> <section> diff --git a/erts/doc/src/alt_dist.xml b/erts/doc/src/alt_dist.xml index 038950b54d..e4912576f7 100644 --- a/erts/doc/src/alt_dist.xml +++ b/erts/doc/src/alt_dist.xml @@ -1,10 +1,10 @@ -<?xml version="1.0" encoding="latin1" ?> +<?xml version="1.0" encoding="utf-8" ?> <!DOCTYPE chapter SYSTEM "chapter.dtd"> <chapter> <header> <copyright> - <year>2000</year><year>2011</year> + <year>2000</year><year>2013</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> diff --git a/erts/doc/src/book.xml b/erts/doc/src/book.xml index 00a2888685..dc02edc5c6 100644 --- a/erts/doc/src/book.xml +++ b/erts/doc/src/book.xml @@ -1,10 +1,10 @@ -<?xml version="1.0" encoding="latin1" ?> +<?xml version="1.0" encoding="utf-8" ?> <!DOCTYPE book SYSTEM "book.dtd"> <book xmlns:xi="http://www.w3.org/2001/XInclude"> <header titlestyle="normal"> <copyright> - <year>1997</year><year>2009</year> + <year>1997</year><year>2013</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> diff --git a/erts/doc/src/communication.xml b/erts/doc/src/communication.xml index 61a9b0e716..02040c9edb 100644 --- a/erts/doc/src/communication.xml +++ b/erts/doc/src/communication.xml @@ -1,4 +1,4 @@ -<?xml version="1.0" encoding="latin1" ?> +<?xml version="1.0" encoding="utf-8" ?> <!DOCTYPE chapter SYSTEM "chapter.dtd"> <chapter> diff --git a/erts/doc/src/crash_dump.xml b/erts/doc/src/crash_dump.xml index 8f5515baca..2b5fc877c3 100644 --- a/erts/doc/src/crash_dump.xml +++ b/erts/doc/src/crash_dump.xml @@ -1,4 +1,4 @@ -<?xml version="1.0" encoding="latin1" ?> +<?xml version="1.0" encoding="utf-8" ?> <!DOCTYPE chapter SYSTEM "chapter.dtd"> <chapter> @@ -85,20 +85,22 @@ operating system.</p> <list type="bulleted"> <item>"<em><A></em>: Cannot allocate <em><N></em> - bytes of memory (of type "<em><T></em>")." - The system - has run out of memory. <A> is the allocator that failed - to allocate memory, <N> is the number of bytes that - <A> tried to allocate, and <T> is the memory block - type that the memory was needed for. The most common case is - that a process stores huge amounts of data. In this case - <T> is most often <c><![CDATA[heap]]></c>, <c><![CDATA[old_heap]]></c>, - <c><![CDATA[heap_frag]]></c>, or <c><![CDATA[binary]]></c>. For more information on - allocators see - <seealso marker="erts_alloc">erts_alloc(3)</seealso>.</item> + bytes of memory (of type "<em><T></em>", thread + <em><I></em>em>)." - The system has run out of memory. <A> + is the allocator that failed to allocate memory, <N> is the + number of bytes that <A> tried to allocate, <T> is the + memory block type that the memory was needed for, and <I> is the + thread identifier. The most common case is that a process stores huge + amounts of data. In this case <T> is most often + <c><![CDATA[heap]]></c>, <c><![CDATA[old_heap]]></c>, + <c><![CDATA[heap_frag]]></c>, or <c><![CDATA[binary]]></c>. + For more information on allocators see + <seealso marker="erts_alloc">erts_alloc(3)</seealso>.</item> <item>"<em><A></em>: Cannot reallocate <em><N></em> - bytes of memory (of type "<em><T></em>")." - Same as - above with the exception that memory was being reallocated - instead of being allocated when the system ran out of memory.</item> + bytes of memory (of type "<em><T></em>", thread + <em><I></em>em>)." - Same as above with the exception that memory + was being reallocated instead of being allocated when the system ran + out of memory.</item> <item>"Unexpected op code <em>N</em>" - Error in compiled code, <c><![CDATA[beam]]></c> file damaged or error in the compiler.</item> <item>"Module <em>Name</em> undefined" <c><![CDATA[|]]></c> "Function @@ -113,8 +115,9 @@ sockets/pipes can be used simultaneously by Erlang (due to limitations in the Unix <c><![CDATA[select]]></c> call). The number of open regular files is not affected by this.</item> - <item>"Received SIGUSR1" - The SIGUSR1 signal was sent to the - Erlang machine (Unix only).</item> + <item>"Received SIGUSR1" - Sending the SIGUSR1 signal to a + Erlang machine (Unix only) forces a crash dump. This slogan reflects + that the Erlang machine crash-dumped due to receiving that signal.</item> <item>"Kernel pid terminated (<em>Who</em>) (<em>Exit-reason</em>)" - The kernel supervisor has detected a failure, usually that the <c><![CDATA[application_controller]]></c> @@ -246,6 +249,9 @@ <tag><em>Last scheduled in for | Current call</em></tag> <item>The current function of the process. These fields will not always exist.</item> + <tag><em>Run queue</em></tag> + <item>The identifier of the scheduler run queue in which the process is + running.</item> <tag><em>Spawned by</em></tag> <item>The parent of the process, i.e. the process which executed <c><![CDATA[spawn]]></c> or <c><![CDATA[spawn_link]]></c>.</item> diff --git a/erts/doc/src/driver.xml b/erts/doc/src/driver.xml index 52283879c7..616703fdef 100644 --- a/erts/doc/src/driver.xml +++ b/erts/doc/src/driver.xml @@ -1,10 +1,10 @@ -<?xml version="1.0" encoding="latin1" ?> +<?xml version="1.0" encoding="utf-8" ?> <!DOCTYPE chapter SYSTEM "chapter.dtd"> <chapter> <header> <copyright> - <year>2001</year><year>2011</year> + <year>2001</year><year>2013</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> diff --git a/erts/doc/src/driver_entry.xml b/erts/doc/src/driver_entry.xml index c37138e7b1..b34ca136f3 100644 --- a/erts/doc/src/driver_entry.xml +++ b/erts/doc/src/driver_entry.xml @@ -1,10 +1,10 @@ -<?xml version="1.0" encoding="latin1" ?> +<?xml version="1.0" encoding="utf-8" ?> <!DOCTYPE cref SYSTEM "cref.dtd"> <cref> <header> <copyright> - <year>2001</year><year>2012</year> + <year>2001</year><year>2013</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -110,6 +110,8 @@ <p>When the driver has passed the <c>driver_entry</c> over to the emulator, the driver is <em>not</em> allowed to modify the <c>driver_entry</c>.</p> + <p>If compiling a driver for static inclusion via --enable-static-drivers you + have to define STATIC_ERLANG_DRIVER before the DRIVER_INIT declaration.</p> <note> <p>Do <em>not</em> declare the <c>driver_entry</c> <c>const</c>. This since the emulator needs to modify the <c>handle</c>, and the <c>handle2</c> @@ -243,10 +245,14 @@ typedef struct erl_drv_entry { something that the <c>WaitForMultipleObjects</c> API function understands). (Some trickery in the emulator allows more than the built-in limit of 64 <c>Events</c> to be used.)</p> + <p>On Enea OSE the <c>event</c> is one or more signals that can + be retrieved using <seealso marker="ose:ose_erl_driver#erl_drv_ose_get_signal">erl_drv_ose_get_signal</seealso>.</p> <p>To use this with threads and asynchronous routines, create a - pipe on unix and an Event on Windows. When the routine + pipe on unix, an Event on Windows or a unique signal number on + Enea OSE. When the routine completes, write to the pipe (use <c>SetEvent</c> on - Windows), this will make the emulator call + Windows or send a message to the emulator process on Enea OSE), + this will make the emulator call <c>ready_input</c> or <c>ready_output</c>.</p> <p>Spurious events may happen. That is, calls to <c>ready_input</c> or <c>ready_output</c> even though no real events are signaled. In diff --git a/erts/doc/src/epmd.xml b/erts/doc/src/epmd.xml index 3e7005410f..25f819ab50 100644 --- a/erts/doc/src/epmd.xml +++ b/erts/doc/src/epmd.xml @@ -1,10 +1,10 @@ -<?xml version="1.0" encoding="latin1" ?> +<?xml version="1.0" encoding="utf-8" ?> <!DOCTYPE comref SYSTEM "comref.dtd"> <comref> <header> <copyright> - <year>1996</year><year>2011</year> + <year>1996</year><year>2013</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -58,12 +58,12 @@ of the IP address and a port number. The name of the node is an atom on the form of <c><![CDATA[Name@Node]]></c>. The job of the <c><![CDATA[epmd]]></c> daemon is to keep track of which - node name listens on which address. Hence, <c><![CDATA[epmd]]></c> map + node name listens on which address. Hence, <c><![CDATA[epmd]]></c> maps symbolic node names to machine addresses.</p> <p>The TCP/IP <c>epmd</c> daemon actually only keeps track of - the <c>Name</c> (first) part of an Erlang node name, the <c>Host</c> - part (whatever is after the <c><![CDATA[@]]></c> is implicit in the + the <c>Name</c> (first) part of an Erlang node name. The <c>Host</c> + part (whatever is after the <c><![CDATA[@]]></c>) is implicit in the node name where the <c>epmd</c> daemon was actually contacted, as is the IP address where the Erlang node can be reached. Consistent and correct TCP naming services are @@ -77,12 +77,12 @@ <p>The daemon is started automatically by the <c>erl</c> command if the node is to be distributed and there is no running instance present. If automatically launched, - environment variables has to be used to alter the behavior of + environment variables have to be used to alter the behavior of the daemon. See the <seealso marker="#environment_variables">Environment variables</seealso> section below.</p> - <p>If the -daemon argument is not given, the + <p>If the -daemon argument is not given, <c><![CDATA[epmd]]></c> runs as a normal program with the controlling terminal of the shell in which it is started. Normally, it should run as a daemon.</p> @@ -122,7 +122,7 @@ comma-separated list of IP addresses and on the loopback address (which is implicitly added to the list if it has not been specified). This can also be set using the - <c><![CDATA[ERL_EPMD_ADDRESS]]></c> environment variable, see the + <c><![CDATA[ERL_EPMD_ADDRESS]]></c> environment variable. See the section <seealso marker="#environment_variables">Environment variables</seealso> below.</p> </item> @@ -130,7 +130,7 @@ <item> <p>Let this instance of epmd listen to another TCP port than default 4369. This can also be set using the - <c><![CDATA[ERL_EPMD_PORT]]></c> environment variable, see the + <c><![CDATA[ERL_EPMD_PORT]]></c> environment variable. See the section <seealso marker="#environment_variables">Environment variables</seealso> below</p> </item> @@ -153,7 +153,7 @@ <p>With relaxed command checking, the <c>epmd</c> daemon can be killed from the localhost with i.e. <c>epmd -kill</c> even if there are active nodes registered. Normally only daemons with an empty node database can be killed with the <c>epmd -kill</c> command.</p> </item> <item> - <p>The <c>epmd -stop</c> command (and the corresponding messages to epmd, as can be given using <c>erl_interface/ei</c>) is normally always ignored, as it opens up for strange situation when two nodes of the same name can be alive at the same time. A node unregisters itself by just closing the connection to epmd, why the <c>stop</c> command was only intended for use in debugging situations.</p> + <p>The <c>epmd -stop</c> command (and the corresponding messages to epmd, as can be given using <c>erl_interface/ei</c>) is normally always ignored, as it opens up the possibility of a strange situation where two nodes of the same name can be alive at the same time. A node unregisters itself by just closing the connection to epmd, which is why the <c>stop</c> command was only intended for use in debugging situations.</p> <p>With relaxed command checking enabled, you can forcibly unregister live nodes.</p> </item> </list> @@ -166,7 +166,7 @@ <section> <marker id="debug_flags"></marker> <title>DbgExtra options</title> - <p>These options are purely for debugging and testing epmd clients, they should not be used in normal operation.</p> + <p>These options are purely for debugging and testing epmd clients. They should not be used in normal operation.</p> <taglist> <tag><c><![CDATA[-packet_timeout Seconds]]></c></tag> @@ -177,9 +177,9 @@ </item> <tag><c><![CDATA[-delay_accept Seconds]]></c></tag> <item> - <p>To simulate a busy server you can insert a delay between epmd - gets notified about that a new connection is requested and - when the connections gets accepted.</p> + <p>To simulate a busy server you can insert a delay between when epmd + gets notified that a new connection is requested and + when the connection gets accepted.</p> </item> <tag><c><![CDATA[-delay_write Seconds]]></c></tag> <item> @@ -191,15 +191,15 @@ <section> <marker id="interactive_flags"></marker> <title>Interactive options</title> - <p>These options make <c>epmd</c> run as an interactive command displaying the results of sending queries ta an already running instance of <c>epmd</c>. The epmd contacted is always on the local node, but the <c>-port</c> option can be used to select between instances if several are running using different port on the host.</p> + <p>These options make <c>epmd</c> run as an interactive command, displaying the results of sending queries to an already running instance of <c>epmd</c>. The epmd contacted is always on the local node, but the <c>-port</c> option can be used to select between instances if several are running using different ports on the host.</p> <taglist> <tag><c><![CDATA[-port No]]></c></tag> <item> <p>Contacts the <c>epmd</c> listening on the given TCP port number (default 4369). This can also be set using the - <c><![CDATA[ERL_EPMD_PORT]]></c> environment variable, see the + <c><![CDATA[ERL_EPMD_PORT]]></c> environment variable. See the section <seealso marker="#environment_variables">Environment - variables</seealso> below</p> + variables</seealso> below.</p> </item> <tag><c><![CDATA[-names]]></c></tag> <item> @@ -210,7 +210,7 @@ <p>Kill the currently running <c>epmd</c>.</p> <p>Killing the running <c>epmd</c> is only allowed if <c>epmd - -names</c> show an empty database or + -names</c> shows an empty database or <c>-relaxed_command_check</c> was given when the running instance of <c>epmd</c> was started. Note that <c>-relaxed_command_check</c> is given when starting the @@ -228,7 +228,7 @@ <p>This command can only be used when contacting <c>epmd</c> instances started with the <c>-relaxed_command_check</c> flag. Note that relaxed command checking has to be enabled for - the <c>epmd</c> daemon contacted, When running epmd + the <c>epmd</c> daemon contacted. When running epmd interactively, <c>-relaxed_command_check</c> has no effect.</p> </item> @@ -259,7 +259,7 @@ <item> <p>If set prior to start, the <c>epmd</c> daemon will behave as if the <c>-relaxed_command_check</c> option was given at - start-up. If consequently setting this option before starting + start-up. Consequently, if this option is set before starting the Erlang virtual machine, the automatically started <c>epmd</c> will accept the <c>-kill</c> and <c>-stop</c> commands without restrictions.</p> @@ -287,8 +287,8 @@ remote hosts. However, only the query commands are answered (and acted upon) if the query comes from a remote host. It is always an error to try to register a nodename if the client is not a process - located on the same host as the <c>epmd</c> instance is running on, - why such requests are considered hostile and the connection is + located on the same host as the <c>epmd</c> instance is running on- + such requests are considered hostile and the connection is immediately closed.</p> <p>The queries accepted from remote nodes are:</p> @@ -307,3 +307,4 @@ </comref> + diff --git a/erts/doc/src/erl.xml b/erts/doc/src/erl.xml index 70569b1c6c..f08467bfc6 100644 --- a/erts/doc/src/erl.xml +++ b/erts/doc/src/erl.xml @@ -1,4 +1,4 @@ -<?xml version="1.0" encoding="latin1" ?> +<?xml version="1.0" encoding="utf-8" ?> <!DOCTYPE comref SYSTEM "comref.dtd"> <comref> @@ -495,7 +495,7 @@ <c><![CDATA[werl]]></c>, not <c><![CDATA[erl]]></c> (<c><![CDATA[oldshell]]></c>). Note also that <c><![CDATA[Ctrl-Break]]></c> is used instead of <c><![CDATA[Ctrl-C]]></c> on Windows.</p> </item> - <tag><c><![CDATA[+c]]></c></tag> + <tag><marker id="+c"><c><![CDATA[+c]]></c></marker></tag> <item> <p>Disable compensation for sudden changes of system time.</p> <p>Normally, <c><![CDATA[erlang:now/0]]></c> will not immediately reflect @@ -510,6 +510,9 @@ reflect the current system time. Note that timers are based on <c><![CDATA[erlang:now/0]]></c>. If the system time jumps, timers then time out at the wrong time.</p> + <p><em>NOTE</em>: You can check whether the adjustment is enabled or + disabled by calling + <seealso marker="erlang#system_info_tolerant_timeofday">erlang:system_info(tolerant_timeofday)</seealso>.</p> </item> <tag><c><![CDATA[+d]]></c></tag> <item> @@ -522,9 +525,10 @@ core dump and no crash dump if an internal error is detected.</p> <p>Calling <c>erlang:halt/1</c> with a string argument will still - produce a crash dump.</p> + produce a crash dump. On Unix systems, sending an emulator process + a SIGUSR1 signal will also force a crash dump.</p> </item> - <tag><c><![CDATA[+e Number]]></c></tag> + <tag><marker id="+e"><c><![CDATA[+e Number]]></c></marker></tag> <item> <p>Set max number of ETS tables.</p> </item> @@ -535,12 +539,15 @@ </item> <tag><marker id="file_name_encoding"></marker><c><![CDATA[+fnl]]></c></tag> <item> - <p>The VM works with file names as if they are encoded using the ISO-latin-1 encoding, disallowing Unicode characters with codepoints beyond 255. This is default on operating systems that have transparent file naming, i.e. all Unixes except MacOSX.</p> - <p>See <seealso marker="stdlib:unicode_usage#unicode_file_names">STDLIB User's Guide</seealso> for more infomation about unicode file names.</p> + <p>The VM works with file names as if they are encoded using the ISO-latin-1 encoding, disallowing Unicode characters with codepoints beyond 255.</p> + <p>See <seealso marker="stdlib:unicode_usage#unicode_file_names">STDLIB User's Guide</seealso> for more infomation about unicode file names. Note that this value also applies to command-line parameters and environment variables (see <seealso marker="stdlib:unicode_usage#unicode_in_environment_and_parameters">STDLIB User's Guide</seealso>).</p> </item> <tag><c><![CDATA[+fnu[{w|i|e}]]]></c></tag> <item> - <p>The VM works with file names as if they are encoded using UTF-8 (or some other system specific Unicode encoding). This is the default on operating systems that enforce Unicode encoding, i.e. Windows and MacOSX.</p> + <p>The VM works with file names as if they are encoded using + UTF-8 (or some other system specific Unicode encoding). This + is the default on operating systems that enforce Unicode + encoding, i.e. Windows and MacOS X.</p> <p>The <c>+fnu</c> switch can be followed by <c>w</c>, <c>i</c>, or <c>e</c> to control the way wrongly encoded file names are to be reported. <c>w</c> means that a warning is @@ -552,11 +559,16 @@ encountered. <c>w</c> is the default. Note that <c>file:read_link/1</c> will always return an error if the link points to an invalid file name.</p> - <p>See <seealso marker="stdlib:unicode_usage#unicode_file_names">STDLIB User's Guide</seealso> for more infomation about unicode file names.</p> + <p>See <seealso marker="stdlib:unicode_usage#unicode_file_names">STDLIB User's Guide</seealso> for more infomation about unicode file names. Note that this value also applies to command-line parameters and environment variables (see <seealso marker="stdlib:unicode_usage#unicode_in_environment_and_parameters">STDLIB User's Guide</seealso>).</p> </item> <tag><c><![CDATA[+fna[{w|i|e}]]]></c></tag> <item> - <p>Selection between <c>+fnl</c> and <c>+fnu</c> is done based on the current locale settings in the OS, meaning that if you have set your terminal for UTF-8 encoding, the filesystem is expected to use the same encoding for file names (use with care).</p> + <p>Selection between <c>+fnl</c> and <c>+fnu</c> is done based + on the current locale settings in the OS, meaning that if you + have set your terminal for UTF-8 encoding, the filesystem is + expected to use the same encoding for file names. This is + default on all operating systems except MacOS X and + Windows.</p> <p>The <c>+fna</c> switch can be followed by <c>w</c>, <c>i</c>, or <c>e</c>. This will have effect if the locale settings cause the behavior of <c>+fnu</c> to be selected. @@ -564,7 +576,7 @@ settings cause the behavior of <c>+fnl</c> to be selected, then <c>w</c>, <c>i</c>, or <c>e</c> will not have any effect.</p> - <p>See <seealso marker="stdlib:unicode_usage#unicode_file_names">STDLIB User's Guide</seealso> for more infomation about unicode file names.</p> + <p>See <seealso marker="stdlib:unicode_usage#unicode_file_names">STDLIB User's Guide</seealso> for more infomation about unicode file names. Note that this value also applies to command-line parameters and environment variables (see <seealso marker="stdlib:unicode_usage#unicode_in_environment_and_parameters">STDLIB User's Guide</seealso>).</p> </item> <tag><c><![CDATA[+hms Size]]></c></tag> <item> @@ -576,6 +588,11 @@ <p>Sets the default binary virtual heap size of processes to the size <c><![CDATA[Size]]></c>.</p> </item> + <tag><c><![CDATA[+hpds Size]]></c></tag> + <item> + <p>Sets the initial process dictionary size of processes to the size + <c><![CDATA[Size]]></c>.</p> + </item> <tag><c><![CDATA[+K true | false]]></c></tag> <item> <p>Enables or disables the kernel poll functionality if @@ -748,22 +765,111 @@ </item> <tag><marker id="+S"><c><![CDATA[+S Schedulers:SchedulerOnline]]></c></marker></tag> <item> - <p>Sets the amount of scheduler threads to create and scheduler - threads to set online when SMP support has been enabled. - Valid range for both values are 1-1024. If the - Erlang runtime system is able to determine the amount - of logical processors configured and logical processors available, - <c>Schedulers</c> will default to logical processors configured, - and <c>SchedulersOnline</c> will default to logical processors - available; otherwise, the default values will be 1. <c>Schedulers</c> - may be omitted if <c>:SchedulerOnline</c> is not and vice versa. The - amount of schedulers online can be changed at run time via + <p>Sets the number of scheduler threads to create and scheduler + threads to set online when SMP support has been enabled. The maximum for + both values is 1024. If the Erlang runtime system is able to determine the + amount of logical processors configured and logical processors available, + <c>Schedulers</c> will default to logical processors configured, and + <c>SchedulersOnline</c> will default to logical processors available; + otherwise, the default values will be 1. <c>Schedulers</c> may be omitted + if <c>:SchedulerOnline</c> is not and vice versa. The number of schedulers + online can be changed at run time via + <seealso marker="erlang#system_flag_schedulers_online">erlang:system_flag(schedulers_online, SchedulersOnline)</seealso>. + </p> + <p>If <c>Schedulers</c> or <c>SchedulersOnline</c> is specified as a + negative number, the value is subtracted from the default number of + logical processors configured or logical processors available, respectively. + </p> + <p>Specifying the value 0 for <c>Schedulers</c> or <c>SchedulersOnline</c> + resets the number of scheduler threads or scheduler threads online respectively + to its default value. + </p> + <p>This option is ignored if the emulator doesn't have + SMP support enabled (see the <seealso marker="#smp">-smp</seealso> + flag).</p> + </item> + <tag><marker id="+SP"><c><![CDATA[+SP SchedulersPercentage:SchedulersOnlinePercentage]]></c></marker></tag> + <item> + <p>Similar to <seealso marker="#+S">+S</seealso> but uses percentages to set the + number of scheduler threads to create, based on logical processors configured, + and scheduler threads to set online, based on logical processors available, when + SMP support has been enabled. Specified values must be greater than 0. For example, + <c>+SP 50:25</c> sets the number of scheduler threads to 50% of the logical processors + configured and the number of scheduler threads online to 25% of the logical processors available. + <c>SchedulersPercentage</c> may be omitted if <c>:SchedulersOnlinePercentage</c> is + not and vice versa. The number of schedulers online can be changed at run time via <seealso marker="erlang#system_flag_schedulers_online">erlang:system_flag(schedulers_online, SchedulersOnline)</seealso>. </p> - <p>This flag will be ignored if the emulator doesn't have + <p>This option interacts with <seealso marker="#+S">+S</seealso> settings. + For example, on a system with 8 logical cores configured and 8 logical cores + available, the combination of the options <c>+S 4:4 +SP 50:25</c> (in either order) + results in 2 scheduler threads (50% of 4) and 1 scheduler thread online (25% of 4). + </p> + <p>This option is ignored if the emulator doesn't have SMP support enabled (see the <seealso marker="#smp">-smp</seealso> flag).</p> </item> + <tag><marker id="+SDcpu"><c><![CDATA[+SDcpu DirtyCPUSchedulers:DirtyCPUSchedulersOnline]]></c></marker></tag> + <item> + <p>Sets the number of dirty CPU scheduler threads to create and dirty + CPU scheduler threads to set online when threading support has been + enabled. The maximum for both values is 1024, and each value is further + limited by the settings for normal schedulers: the number of dirty CPU + scheduler threads created cannot exceed the number of normal scheduler + threads created, and the number of dirty CPU scheduler threads online + cannot exceed the number of normal scheduler threads online (see the + <seealso marker="#+S">+S</seealso> and <seealso marker="#+SP">+SP</seealso> + flags for more details). By default, the number of dirty CPU scheduler + threads created equals the number of normal scheduler threads created, + and the number of dirty CPU scheduler threads online equals the number + of normal scheduler threads online. <c>DirtyCPUSchedulers</c> may be + omitted if <c>:DirtyCPUSchedulersOnline</c> is not and vice versa. The + number of dirty CPU schedulers online can be changed at run time via + <seealso marker="erlang#system_flag_dirty_cpu_schedulers_online">erlang:system_flag(dirty_cpu_schedulers_online, DirtyCPUSchedulersOnline)</seealso>. + </p> + <p>This option is ignored if the emulator doesn't have threading support + enabled. Currently, <em>this option is experimental</em> and is supported only + if the emulator was configured and built with support for dirty schedulers + enabled (it's disabled by default). + </p> + </item> + <tag><marker id="+SDPcpu"><c><![CDATA[+SDPcpu DirtyCPUSchedulersPercentage:DirtyCPUSchedulersOnlinePercentage]]></c></marker></tag> + <item> + <p>Similar to <seealso marker="#+SDcpu">+SDcpu</seealso> but uses percentages to set the + number of dirty CPU scheduler threads to create and number of dirty CPU scheduler threads + to set online when threading support has been enabled. Specified values must be greater + than 0. For example, <c>+SDPcpu 50:25</c> sets the number of dirty CPU scheduler threads + to 50% of the logical processors configured and the number of dirty CPU scheduler threads + online to 25% of the logical processors available. <c>DirtyCPUSchedulersPercentage</c> may + be omitted if <c>:DirtyCPUSchedulersOnlinePercentage</c> is not and vice versa. The + number of dirty CPU schedulers online can be changed at run time via + <seealso marker="erlang#system_flag_dirty_cpu_schedulers_online">erlang:system_flag(dirty_cpu_schedulers_online, DirtyCPUSchedulersOnline)</seealso>. + </p> + <p>This option interacts with <seealso marker="#+SDcpu">+SDcpu</seealso> settings. + For example, on a system with 8 logical cores configured and 8 logical cores available, + the combination of the options <c>+SDcpu 4:4 +SDPcpu 50:25</c> (in either order) results + in 2 dirty CPU scheduler threads (50% of 4) and 1 dirty CPU scheduler thread online (25% of 4). + </p> + <p>This option is ignored if the emulator doesn't have threading support + enabled. Currently, <em>this option is experimental</em> and is supported only + if the emulator was configured and built with support for dirty schedulers + enabled (it's disabled by default). + </p> + </item> + <tag><marker id="+SDio"><c><![CDATA[+SDio IOSchedulers]]></c></marker></tag> + <item> + <p>Sets the number of dirty I/O scheduler threads to create when threading + support has been enabled. The valid range is 0-1024. By default, the number + of dirty I/O scheduler threads created is 10, same as the default number of + threads in the <seealso marker="#async_thread_pool_size">async thread pool + </seealso>. + </p> + <p>This option is ignored if the emulator doesn't have threading support + enabled. Currently, <em>this option is experimental</em> and is supported only + if the emulator was configured and built with support for dirty schedulers + enabled (it's disabled by default). + </p> + </item> <tag><c><![CDATA[+sFlag Value]]></c></tag> <item> <p>Scheduling specific flags.</p> @@ -913,6 +1019,10 @@ when schedulers frequently run out of work. When disabled, the frequency with which schedulers run out of work will not be taken into account by the load balancing logic. + <br/> <c>+scl false</c> is similar to + <seealso marker="#+sub">+sub true</seealso> with the difference + that <c>+sub true</c> also will balance scheduler utilization + between schedulers. </p> </item> <tag><marker id="+sct"><c>+sct CpuTopology</c></marker></tag> @@ -1037,6 +1147,23 @@ <p>For more information, see <seealso marker="erlang#system_info_cpu_topology">erlang:system_info(cpu_topology)</seealso>.</p> </item> + <tag><marker id="+secio"><c>+secio true|false</c></marker></tag> + <item> + <p>Enable or disable eager check I/O scheduling. The default + is currently <c>false</c>, but will most likely be changed + to <c>true</c> in OTP 18. The behaviour before this flag + was introduced corresponds to <c>+secio false</c>.</p> + <p>The flag effects when schedulers will check for I/O + operations possible to execute, and when such I/O operations + will execute. As the name of the parameter implies, + schedulers will be more eager to check for I/O when + <c>true</c> is passed. This however also implies that + execution of outstanding I/O operation will not be + prioritized to the same extent as when <c>false</c> is + passed.</p> + <p><seealso marker="erlang#system_info_eager_check_io"><c>erlang:system_info(eager_check_io)</c></seealso> + returns the value of this parameter used when starting the VM.</p> + </item> <tag><marker id="+sfwi"><c>+sfwi Interval</c></marker></tag> <item> <p>Set scheduler forced wakeup interval. All run queues will @@ -1059,7 +1186,30 @@ documentation of the <seealso marker="#+sbt">+sbt</seealso> flag. </p> </item> - <tag><marker id="+swct"><c>+sws very_eager|eager|medium|lazy|very_lazy</c></marker></tag> + <tag><marker id="+sub"><c>+sub true|false</c></marker></tag> + <item> + <p>Enable or disable + <seealso marker="erts:erlang#statistics_scheduler_wall_time">scheduler + utilization</seealso> balancing of load. By default scheduler + utilization balancing is disabled and instead scheduler + compaction of load is enabled which will strive for a load + distribution which causes as many scheduler threads as possible + to be fully loaded (i.e., not run out of work). When scheduler + utilization balancing is enabled the system will instead try to + balance scheduler utilization between schedulers. That is, + strive for equal scheduler utilization on all schedulers. + <br/> <c>+sub true</c> is only supported on + systems where the runtime system detects and use a monotonically + increasing high resolution clock. On other systems, the runtime + system will fail to start. + <br/> <c>+sub true</c> implies + <seealso marker="#+scl">+scl false</seealso>. The difference + between <c>+sub true</c> and <c>+scl false</c> is that + <c>+scl false</c> will not try to balance the scheduler + utilization. + </p> + </item> + <tag><marker id="+swct"><c>+swct very_eager|eager|medium|lazy|very_lazy</c></marker></tag> <item> <p> Set scheduler wake cleanup threshold. Default is <c>medium</c>. @@ -1098,18 +1248,18 @@ <tag><marker id="+spp"><c>+spp Bool</c></marker></tag> <item> <p>Set default scheduler hint for port parallelism. If set to - <c>true</c>, the VM will schedule port tasks when it by this can - improve the parallelism in the system. If set to <c>false</c>, - the VM will try to perform port tasks immediately and by this - improve latency at the expense of parallelism. If this - flag has not been passed, the default scheduler hint for port - parallelism is currently <c>false</c>. The default used can be - inspected in runtime by calling - <seealso marker="erlang#system_info_port_parallelism">erlang:system_info(port_parallelism)</seealso>. + <c>true</c>, the VM will schedule port tasks when doing so will + improve parallelism in the system. If set to <c>false</c>, the VM + will try to perform port tasks immediately, improving latency at the + expense of parallelism. If this flag has not been passed, the + default scheduler hint for port parallelism is currently + <c>false</c>. The default used can be inspected in runtime by + calling <seealso + marker="erlang#system_info_port_parallelism">erlang:system_info(port_parallelism)</seealso>. The default can be overriden on port creation by passing the <seealso marker="erlang#open_port_parallelism">parallelism</seealso> - option to - <seealso marker="erlang#open_port/2">open_port/2</seealso></p>. + option to <seealso + marker="erlang#open_port/2">open_port/2</seealso></p>. </item> <tag><marker id="sched_thread_stack_size"><c><![CDATA[+sss size]]></c></marker></tag> <item> diff --git a/erts/doc/src/erl_dist_protocol.xml b/erts/doc/src/erl_dist_protocol.xml index 84f4be208d..890293d802 100644 --- a/erts/doc/src/erl_dist_protocol.xml +++ b/erts/doc/src/erl_dist_protocol.xml @@ -1,4 +1,4 @@ -<?xml version="1.0" encoding="iso-8859-1" ?> +<?xml version="1.0" encoding="utf-8" ?> <!DOCTYPE chapter SYSTEM "chapter.dtd"> <chapter> diff --git a/erts/doc/src/erl_driver.xml b/erts/doc/src/erl_driver.xml index efe0483b31..77fc906aca 100644 --- a/erts/doc/src/erl_driver.xml +++ b/erts/doc/src/erl_driver.xml @@ -1,10 +1,10 @@ -<?xml version="1.0" encoding="latin1" ?> +<?xml version="1.0" encoding="utf-8" ?> <!DOCTYPE cref SYSTEM "cref.dtd"> <cref> <header> <copyright> - <year>2001</year><year>2013</year> + <year>2001</year><year>2014</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -315,10 +315,13 @@ <c>ERL_DRV_EXTENDED_MINOR_VERSION</c> will be incremented when new features are added. The runtime system uses the minor version of the driver to determine what features to use. - The runtime system will refuse to load a driver if the major + The runtime system will normally refuse to load a driver if the major versions differ, or if the major versions are equal and the minor version used by the driver is greater than the one used - by the runtime system.</p> + by the runtime system. Old drivers with lower major versions + will however be allowed after a bump of the major version during + a transition period of two major releases. Such old drivers might + however fail if deprecated features are used.</p> <p>The emulator will refuse to load a driver that does not use the extended driver interface, to allow for 64-bit capable drivers, @@ -543,6 +546,7 @@ typedef struct ErlDrvSysInfo { int scheduler_threads; int nif_major_version; int nif_minor_version; + int dirty_scheduler_support; } ErlDrvSysInfo; </code> @@ -607,6 +611,10 @@ typedef struct ErlDrvSysInfo { <tag><c>nif_minor_version</c></tag> <item>The value of <c>ERL_NIF_MINOR_VERSION</c> when the runtime system was compiled. </item> + <tag><c>dirty_scheduler_support</c></tag> + <item>A value <c>!= 0</c> if the runtime system has support for dirty scheduler threads; + otherwise <c>0</c>. + </item> </taglist> </item> <tag><marker id="ErlDrvBinary"/>ErlDrvBinary</tag> @@ -666,7 +674,7 @@ typedef struct ErlDrvBinary { <item> <p>The <c>ErlDrvData</c> is a handle to driver-specific data, passed to the driver call-backs. It is a pointer, and is - most often type casted to a specific pointer in the driver.</p> + most often type cast to a specific pointer in the driver.</p> </item> <tag>SysIOVec</tag> <item> @@ -745,7 +753,7 @@ typedef struct ErlIOVec { created and decrement it once when the port associated with the lock terminates. The emulator will also increment the reference count when an async job is enqueued and decrement - it after an async job has been invoked, or canceled. Besides + it after an async job has been invoked. Besides this, it is the responsibility of the driver to ensure that the reference count does not reach zero before the last use of the lock by the driver has been made. The reference count @@ -1014,7 +1022,7 @@ typedef struct ErlIOVec { <fsummary>Read a system timestamp</fsummary> <desc> <marker id="driver_get_now"></marker> - <p>This function reads a timestamp into the memory pointed to by + <p>This function reads a timestamp into the memory pointed to by the parameter <c>now</c>. See the description of <seealso marker="#ErlDrvNowData">ErlDrvNowData</seealso> for specification of its fields. </p> <p>The return value is 0 unless the <c>now</c> pointer is not @@ -1035,7 +1043,9 @@ typedef struct ErlIOVec { <c>select</c>/<c>poll</c> can use). On windows, the Win32 API function <c>WaitForMultipleObjects</c> is used. This places other restrictions on the event object. - Refer to the Win32 SDK documentation.</p> + Refer to the Win32 SDK documentation. + On Enea OSE, the receive function is used. See the <seealso + marker="ose:ose_erl_driver"></seealso> for more details.</p> <p>The <c>on</c> parameter should be <c>1</c> for setting events and <c>0</c> for clearing them.</p> <p>The <c>mode</c> argument is a bitwise-or combination of @@ -1047,7 +1057,7 @@ typedef struct ErlIOVec { <seealso marker="driver_entry#ready_output">ready_output</seealso>. </p> <note> - <p>Some OS (Windows) do not differentiate between read and write events. + <p>Some OS (Windows and Enea OSE) do not differentiate between read and write events. The call-back for a fired event then only depends on the value of <c>mode</c>.</p> </note> <p><c>ERL_DRV_USE</c> specifies if we are using the event object or if we want to close it. @@ -1056,7 +1066,7 @@ typedef struct ErlIOVec { returned. Another thread may still be using the event object internally. To safely close an event object call <c>driver_select</c> with <c>ERL_DRV_USE</c> and <c>on==0</c>. That - will clear all events and then call + will clear all events and then call <seealso marker="driver_entry#stop_select">stop_select</seealso> when it is safe to close the event object. <c>ERL_DRV_USE</c> should be set together with the first event @@ -1068,7 +1078,7 @@ typedef struct ErlIOVec { <p>ERL_DRV_USE was added in OTP release R13. Old drivers will still work as before. But it is recommended to update them to use <c>ERL_DRV_USE</c> and <c>stop_select</c> to make sure that event objects are closed in a safe way.</p> - </note> + </note> <p>The return value is 0 (failure, -1, only if the <c>ready_input</c>/<c>ready_output</c> is <c>NULL</c>).</p> @@ -1524,7 +1534,7 @@ typedef struct ErlIOVec { <marker id="remove_driver_entry"></marker> <p>This function removes a driver entry <c>de</c> previously added with <c>add_driver_entry</c>.</p> - <p>Driver entries added by the <c>erl_ddll</c> erlang interface can + <p>Driver entries added by the <c>erl_ddll</c> erlang interface can not be removed by using this interface.</p> </desc> </func> @@ -1742,15 +1752,19 @@ typedef struct ErlIOVec { term consists of one to four elements in the array. The term first has a term type, and then arguments. The <c>port</c> parameter specifies the sending port.</p> - <p>Tuple and lists (with the exception of strings, see below), + <p>Tuples, maps and lists (with the exception of strings, see below), are built in reverse polish notation, so that to build a tuple, the elements are given first, and then the tuple - term, with a count. Likewise for lists.</p> + term, with a count. Likewise for lists and maps.</p> <p>A tuple must be specified with the number of elements. (The elements precede the <c>ERL_DRV_TUPLE</c> term.)</p> <p>A list must be specified with the number of elements, including the tail, which is the last term preceding <c>ERL_DRV_LIST</c>.</p> + <p>A map must be specified with the number of key-value pairs <c>N</c>. + The key-value pairs must precede the <c>ERL_DRV_MAP</c> in this order: + <c>key1,value1,key2,value2,...,keyN,valueN</c>. + Duplicate keys are not allowed.</p> <p>The special term <c>ERL_DRV_STRING_CONS</c> is used to "splice" in a string in a list, a string given this way is not a list per se, but the elements are elements of the @@ -1758,7 +1772,7 @@ typedef struct ErlIOVec { <pre> Term type Argument(s) =========================================== -ERL_DRV_NIL +ERL_DRV_NIL ERL_DRV_ATOM ErlDrvTermData atom (from driver_mk_atom(char *string)) ERL_DRV_INT ErlDrvSInt integer ERL_DRV_UINT ErlDrvUInt integer @@ -1774,16 +1788,17 @@ ERL_DRV_PID ErlDrvTermData pid (from driver_connected(ErlDrvPort port) ERL_DRV_STRING_CONS char *str, int len ERL_DRV_FLOAT double *dbl ERL_DRV_EXT2TERM char *buf, ErlDrvUInt len +ERL_DRV_MAP int sz </pre> <p>The unsigned integer data type <c>ErlDrvUInt</c> and the signed integer data type <c>ErlDrvSInt</c> are 64 bits wide on a 64 bit runtime system and 32 bits wide on a 32 bit runtime system. They were introduced in erts version 5.6, - and replaced some of the <c>int</c> arguments in the list above. + and replaced some of the <c>int</c> arguments in the list above. </p> <p>The unsigned integer data type <c>ErlDrvUInt64</c> and the signed integer data type <c>ErlDrvSInt64</c> are always 64 bits - wide. They were introduced in erts version 5.7.4. + wide. They were introduced in erts version 5.7.4. </p> <p>To build the tuple <c>{tcp, Port, [100 | Binary]}</c>, the @@ -1856,6 +1871,24 @@ ERL_DRV_EXT2TERM char *buf, ErlDrvUInt len }; erl_drv_output_term(driver_mk_port(drvport), spec, sizeof(spec) / sizeof(spec[0])); ]]></code> + + <p>To build the map <c>#{key1 => 100, key2 => {200, 300}}</c>, the + following call could be made.</p> + <code type="none"><![CDATA[ + ErlDrvPort port = ... + ErlDrvTermData spec[] = { + ERL_DRV_ATOM, driver_mk_atom("key1"), + ERL_DRV_INT, 100, + ERL_DRV_ATOM, driver_mk_atom("key2"), + ERL_DRV_INT, 200, + ERL_DRV_INT, 300, + ERL_DRV_TUPLE, 2, + ERL_DRV_MAP, 2 + }; + erl_drv_output_term(driver_mk_port(drvport), spec, sizeof(spec) / sizeof(spec[0])); + ]]> + </code> + <p>If you want to pass a binary and don't already have the content of the binary in an <c>ErlDrvBinary</c>, you can benefit from using <c>ERL_DRV_BUF2BINARY</c> instead of creating an <c>ErlDrvBinary</c> @@ -1879,7 +1912,7 @@ ERL_DRV_EXT2TERM char *buf, ErlDrvUInt len <fsummary>Send term data from driver to port owner</fsummary> <desc> <marker id="driver_output_term"></marker> - <warning><p><c>driver_output_term()</c> is deferred and will + <warning><p><c>driver_output_term()</c> is deprecated and will be removed in the OTP-R17 release. Use <seealso marker="#erl_drv_send_term">erl_drv_output_term()</seealso> instead.</p> @@ -1937,7 +1970,7 @@ ERL_DRV_EXT2TERM char *buf, ErlDrvUInt len <fsummary>Send term data to other process than port owner process</fsummary> <desc> <marker id="driver_send_term"></marker> - <warning><p><c>driver_send_term()</c> is deferred and will + <warning><p><c>driver_send_term()</c> is deprecated and will be removed in the OTP-R17 release. Use <seealso marker="#erl_drv_send_term">erl_drv_send_term()</seealso> instead.</p> @@ -1981,7 +2014,7 @@ ERL_DRV_EXT2TERM char *buf, ErlDrvUInt len thread, the following call can be used:</p> <p></p> <code type="none"><![CDATA[ - unsigned int myKey = (unsigned int) myPort; + unsigned int myKey = driver_async_port_key(myPort); r = driver_async(myPort, &myKey, myData, myFunc); ]]></code> @@ -1995,14 +2028,13 @@ ERL_DRV_EXT2TERM char *buf, ErlDrvUInt len <c>async_invoke</c> and <c>async_free</c>. It's typically a pointer to a structure that contains a pipe or event that can be used to signal that the async operation completed. - The data should be freed in <c>async_free</c>, because it's - called if <c>driver_async_cancel</c> is called.</p> + The data should be freed in <c>async_free</c>.</p> <p>When the async operation is done, <seealso marker="driver_entry#ready_async">ready_async</seealso> driver - entry function is called. If <c>async_ready</c> is null in + entry function is called. If <c>ready_async</c> is null in the driver entry, the <c>async_free</c> function is called instead.</p> - <p>The return value is a handle to the asynchronous task, which - can be used as argument to <c>driver_async_cancel</c>.</p> + <p>The return value is -1 if the <c>driver_async</c> call + fails.</p> <note> <p>As of erts version 5.5.4.3 the default stack size for threads in the async-thread pool is 16 kilowords, @@ -2022,23 +2054,21 @@ ERL_DRV_EXT2TERM char *buf, ErlDrvUInt len </desc> </func> <func> - <name><ret>int</ret><nametext>driver_async_cancel(long id)</nametext></name> - <fsummary>Cancel an asynchronous call</fsummary> + <name><ret>unsigned int</ret><nametext>driver_async_port_key (ErlDrvPort port)</nametext></name> + <fsummary>Calculate an async key from an ErlDrvPort</fsummary> <desc> - <marker id="driver_async_cancel"></marker> - <p>This function used to cancel a scheduled asynchronous operation, - if it was still in the queue. It returned 1 if it succeeded, and - 0 if it failed.</p> - <p>Since it could not guarantee success, it was more or less useless. - The user had to implement synchronization of cancellation anyway. - It also unnecessarily complicated the implementation. Therefore, - as of OTP-R15B <c>driver_async_cancel()</c> is deprecated, and - scheduled for removal in OTP-R16. It will currently always fail, - and return 0.</p> - <warning><p><c>driver_async_cancel()</c> is deferred and will - be removed in the OTP-R16 release.</p> - </warning> - + <marker id="driver_async_port_key"></marker> + <p>This function calculates a key for later use in <seealso + marker="#driver_async">driver_async()</seealso>. The keys are + evenly distributed so that a fair mapping between port id's + and async thread id's is achieved.</p> + <note> + <p>Before OTP-R16, the actual port id could be used as a key + with proper casting, but after the rewrite of the port + subsystem, this is no longer the case. With this function, you + can achieve the same distribution based on port id's as before + OTP-R16.</p> + </note> </desc> </func> <func> @@ -2048,7 +2078,7 @@ ERL_DRV_EXT2TERM char *buf, ErlDrvUInt len <marker id="driver_lock_driver"></marker> <p>This function locks the driver used by the port <c>port</c> in memory for the rest of the emulator process' - lifetime. After this call, the driver behaves as one of Erlang's + lifetime. After this call, the driver behaves as one of Erlang's statically linked in drivers.</p> </desc> </func> @@ -2076,7 +2106,7 @@ ERL_DRV_EXT2TERM char *buf, ErlDrvUInt len <seealso marker="driver_entry">driver_entry</seealso>).</item> <tag><c>drv_data</c></tag> <item>The driver defined handle that will be passed in subsequent - calls to driver call-backs. Note, that the + calls to driver call-backs. Note, that the <seealso marker="driver_entry#start">driver start call-back</seealso> will not be called for this new driver instance. The driver defined handle is normally created in the @@ -2284,7 +2314,7 @@ ERL_DRV_EXT2TERM char *buf, ErlDrvUInt len <item>A thread identifier.</item> </taglist> <p>This function compares two thread identifiers for equality, - and returns <c>0</c> it they aren't equal, and + and returns <c>0</c> it they aren't equal, and a value not equal to <c>0</c> if they are equal.</p> <note><p>A Thread identifier may be reused very quickly after a thread has terminated. Therefore, if a thread @@ -2469,7 +2499,7 @@ ERL_DRV_EXT2TERM char *buf, ErlDrvUInt len </taglist> <p>This function broadcasts on a condition variable. That is, if other threads are waiting on the condition variable being - broadcasted on, <em>all</em> of them will be woken. + broadcast on, <em>all</em> of them will be woken. </p> <p>This function is thread-safe.</p> </desc> @@ -2498,7 +2528,7 @@ ERL_DRV_EXT2TERM char *buf, ErlDrvUInt len the calling thread when calling this function. </p> <note><p><c>erl_drv_cond_wait()</c> might return even though - no-one has signaled or broadcasted on the condition + no-one has signaled or broadcast on the condition variable. Code calling <c>erl_drv_cond_wait()</c> should always be prepared for <c>erl_drv_cond_wait()</c> returning even though the condition that the thread was @@ -2822,7 +2852,7 @@ ERL_DRV_EXT2TERM char *buf, ErlDrvUInt len <item>A pointer to an output buffer.</item> <tag><c>value_size</c></tag> <item>A pointer to an integer. The integer is both used for - passing input and output sizes (see below). + passing input and output sizes (see below). </item> </taglist> <p>This function retrieves the value of an environment variable. @@ -2889,8 +2919,84 @@ ERL_DRV_EXT2TERM char *buf, ErlDrvUInt len beginning of this document.</p> </desc> </func> - </funcs> + <func> + <name><ret>char *</ret><nametext>erl_drv_cond_name(ErlDrvCond *cnd)</nametext></name> + <fsummary>Get name of driver mutex.</fsummary> + <desc> + <marker id="erl_drv_cnd_name"></marker> + <p>Arguments:</p> + <taglist> + <tag><c>cnd</c></tag> + <item>A pointer to an initialized condition.</item> + </taglist> + <p> + Returns a pointer to the name of the condition. + </p> + <note> + <p>This function is intended for debugging purposes only.</p> + </note> + </desc> + </func> + + <func> + <name><ret>char *</ret><nametext>erl_drv_mutex_name(ErlDrvMutex *mtx)</nametext></name> + <fsummary>Get name of driver mutex.</fsummary> + <desc> + <marker id="erl_drv_mutex_name"></marker> + <p>Arguments:</p> + <taglist> + <tag><c>mtx</c></tag> + <item>A pointer to an initialized mutex.</item> + </taglist> + <p> + Returns a pointer to the name of the mutex. + </p> + <note> + <p>This function is intended for debugging purposes only.</p> + </note> + </desc> + </func> + + <func> + <name><ret>char *</ret><nametext>erl_drv_rwlock_name(ErlDrvRWLock *rwlck)</nametext></name> + <fsummary>Get name of driver mutex.</fsummary> + <desc> + <marker id="erl_drv_rwlock_name"></marker> + <p>Arguments:</p> + <taglist> + <tag><c>rwlck</c></tag> + <item>A pointer to an initialized r/w-lock.</item> + </taglist> + <p> + Returns a pointer to the name of the r/w-lock. + </p> + <note> + <p>This function is intended for debugging purposes only.</p> + </note> + </desc> + </func> + + <func> + <name><ret>char *</ret><nametext>erl_drv_thread_name(ErlDrvTid tid)</nametext></name> + <fsummary>Get name of driver mutex.</fsummary> + <desc> + <marker id="erl_drv_rwlock_name"></marker> + <p>Arguments:</p> + <taglist> + <tag><c>tid</c></tag> + <item>A thread identifier.</item> + </taglist> + <p> + Returns a pointer to the name of the thread. + </p> + <note> + <p>This function is intended for debugging purposes only.</p> + </note> + </desc> + </func> + + </funcs> <section> <title>SEE ALSO</title> <p><seealso marker="driver_entry">driver_entry(3)</seealso>, @@ -2900,4 +3006,3 @@ ERL_DRV_EXT2TERM char *buf, ErlDrvUInt len Guide Ch. 3)</p> </section> </cref> - diff --git a/erts/doc/src/erl_ext_dist.xml b/erts/doc/src/erl_ext_dist.xml index c6849f3326..a6e7dddbed 100644 --- a/erts/doc/src/erl_ext_dist.xml +++ b/erts/doc/src/erl_ext_dist.xml @@ -1,11 +1,11 @@ -<?xml version="1.0" encoding="iso-8859-1" ?> +<?xml version="1.0" encoding="utf-8" ?> <!DOCTYPE chapter SYSTEM "chapter.dtd"> <chapter> <header> <copyright> <year>2007</year> - <year>2013</year> + <year>2014</year> <holder>Ericsson AB, All Rights Reserved</holder> </copyright> <legalnotice> @@ -126,9 +126,8 @@ However, only characters that can be encoded using Latin1 (ISO-8859-1) are currently supported in atoms. The support for UTF-8 encoded atoms in the external format has been implemented in order to be able to support - all Unicode characters in atoms in <em>some future release</em>. Full - support for Unicode atoms will not happen before OTP-R18, and might - be introduced even later than that. Until full Unicode support for + all Unicode characters in atoms in <em>some future release</em>. + Until full Unicode support for atoms has been introduced, it is an <em>error</em> to pass atoms containing characters that cannot be encoded in Latin1, and <em>the behavior is undefined</em>.</p> @@ -573,6 +572,33 @@ </section> <section> + <marker id="MAP_EXT"/> + <title>MAP_EXT</title> + + <table align="left"> + <row> + <cell align="center">1</cell> + <cell align="center">4</cell> + <cell align="center">N</cell> + </row> + <row> + <cell align="center">116</cell> + <cell align="center">Arity</cell> + <cell align="center">Pairs</cell> + </row> + <tcaption></tcaption></table> + <p> + <c>MAP_EXT</c> encodes a map. The <c>Arity</c> field is an unsigned + 4 byte integer in big endian format that determines the number of + key-value pairs in the map. Key and value pairs (<c>Ki => Vi</c>) + are encoded in the <c>Pairs</c> section in the following order: + <c>K1, V1, K2, V2,..., Kn, Vn</c>. + Duplicate keys are <em>not allowed</em> within the same map. + </p> + <p><em>Since: </em>OTP 17.0</p> + </section> + + <section> <marker id="NIL_EXT"/> <title>NIL_EXT</title> @@ -1014,10 +1040,10 @@ </row> <tcaption></tcaption></table> <p> - This term represents a bitstring whose length in bits is not a - multiple of 8 (created using the bit syntax in R12B and later). + This term represents a bitstring whose length in bits does + not have to be a multiple of 8. The <c>Len</c> field is an unsigned 4 byte integer (big endian). - The <c>Bits</c> field is the number of bits that are used + The <c>Bits</c> field is the number of bits (1-8) that are used in the last byte in the data field, counting from the most significant bit towards the least significant. diff --git a/erts/doc/src/erl_nif.xml b/erts/doc/src/erl_nif.xml index 864b91946a..3de94be9ff 100644 --- a/erts/doc/src/erl_nif.xml +++ b/erts/doc/src/erl_nif.xml @@ -1,4 +1,4 @@ -<?xml version="1.0" encoding="latin1" ?> +<?xml version="1.0" encoding="utf-8" ?> <!DOCTYPE cref SYSTEM "cref.dtd"> <cref> @@ -168,20 +168,26 @@ ok <p><marker id="lengthy_work"/> As mentioned in the <seealso marker="#WARNING">warning</seealso> text at the beginning of this document it is of vital importance that a native function - does return relatively fast. It is hard to give an exact maximum amount + return relatively quickly. It is hard to give an exact maximum amount of time that a native function is allowed to work, but as a rule of thumb - a well behaving native function should return to its caller before a + a well-behaving native function should return to its caller before a millisecond has passed. This can be achieved using different approaches. - If you have full control over the code that are to execute in the native + If you have full control over the code to execute in the native function, the best approach is to divide the work into multiple chunks of - work and call the native function multiple times. Function + work and call the native function multiple times, either directly from Erlang code + or by having a native function schedule a future NIF call via the + <seealso marker="#enif_schedule_nif"> enif_schedule_nif</seealso> function. Function <seealso marker="#enif_consume_timeslice">enif_consume_timeslice</seealso> can be - used this facilitate such work division. In some cases, however, this might not - be possible, e.g. when calling third party libraries. Then you typically want + used to help with such work division. In some cases, however, this might not + be possible, e.g. when calling third-party libraries. Then you typically want to dispatch the work to another thread, return from the native function, and wait for the result. The thread can send the result back to the calling thread using message passing. Information - about thread primitives can be found below.</p> + about thread primitives can be found below. If you have built your system + with <em>the currently experimental</em> support for dirty schedulers, + you may want to try out this functionality by dispatching the work to a + <seealso marker="#dirty_nifs">dirty NIF</seealso>, + which does not have the same duration restriction as a normal NIF.</p> </description> <section> <title>FUNCTIONALITY</title> @@ -312,6 +318,65 @@ ok <p>The library initialization callbacks <c>load</c>, <c>reload</c> and <c>upgrade</c> are all thread-safe even for shared state data.</p> </item> + + <tag><marker id="version_management"/>Version Management</tag> + <item><p> + When a NIF library is built, information about NIF API version + is compiled into the library. When a NIF library is loaded the + runtime system verifies that the library is of a compatible version. + <c>erl_nif.h</c> defines <c>ERL_NIF_MAJOR_VERSION</c>, and + <c>ERL_NIF_MINOR_VERSION</c>. <c>ERL_NIF_MAJOR_VERSION</c> will be + incremented when NIF library incompatible changes are made to the + Erlang runtime system. Normally it will suffice to recompile the NIF + library when the <c>ERL_NIF_MAJOR_VERSION</c> has changed, but it + could, under rare circumstances, mean that NIF libraries have to + be slightly modified. If so, this will of course be documented. + <c>ERL_NIF_MINOR_VERSION</c> will be incremented when + new features are added. The runtime system uses the minor version + to determine what features to use. + </p><p> + The runtime system will normally refuse to load a NIF library if + the major versions differ, or if the major versions are equal and + the minor version used by the NIF library is greater than the one + used by the runtime system. Old NIF libraries with lower major + versions will however be allowed after a bump of the major version + during a transition period of two major releases. Such old NIF + libraries might however fail if deprecated features are used. + </p></item> + + <tag>Long-running NIFs</tag> + <item><p><marker id="dirty_nifs"/>Native functions + <seealso marker="#lengthy_work"> + must normally run quickly</seealso>, as explained earlier in this document. They + generally should execute for no more than a millisecond. But not all native functions + can execute so quickly; for example, functions that encrypt large blocks of data or + perform lengthy file system operations can often run for tens of seconds or more.</p> + <p>If the functionality of a long-running NIF can be split so that its work can be + achieved through a series of shorter NIF calls, the application can either make that series + of NIF calls from the Erlang level, or it can call a NIF that first performs a chunk of the + work, then invokes the <seealso marker="#enif_schedule_nif">enif_schedule_nif</seealso> + function to schedule another NIF call to perform the next chunk. The final call scheduled + in this manner can then return the overall result. Breaking up a long-running function in + this manner enables the VM to regain control between calls to the NIFs, thereby avoiding + degraded responsiveness, scheduler load balancing problems, and other strange behaviours.</p> + <p>A NIF that cannot be split and cannot execute in a millisecond or less is called a "dirty NIF" + because it performs work that the Erlang runtime cannot handle cleanly. + <em>Note that the dirty NIF functionality described here is experimental</em> and that you have to + enable support for dirty schedulers when building OTP in order to try the functionality out. + Applications that make use of such functions must indicate to the runtime that the functions are + dirty so they can be handled specially. To schedule a dirty NIF for execution, the + appropriate flags value can be set for the NIF in its <seealso marker="#ErlNifFunc">ErlNifFunc</seealso> + entry, or the application can call <seealso marker="#enif_schedule_nif">enif_schedule_nif</seealso>, + passing to it a pointer to the dirty NIF to be executed and indicating with the <c>flags</c> + argument whether it expects the operation to be CPU-bound or I/O-bound.</p> + <note><p>Dirty NIF support is available only when the emulator is configured with dirty + schedulers enabled. This feature is currently disabled by default. To determine whether + the dirty NIF API is available, native code can check to see if the C preprocessor macro + <c>ERL_NIF_DIRTY_SCHEDULER_SUPPORT</c> is defined. Also, if the Erlang runtime was built + without threading support, dirty schedulers are disabled. 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> + </item> </taglist> </section> <section> @@ -330,6 +395,8 @@ ok <c>upgrade</c> will be called to initialize the library. <c>unload</c> is called to release the library. They are all described individually below.</p> + <p>If compiling a nif for static inclusion via --enable-static-nifs you + have to define STATIC_ERLANG_NIF before the ERL_NIF_INIT declaration.</p> </item> <tag><marker id="load"/>int (*load)(ErlNifEnv* env, void** priv_data, ERL_NIF_TERM load_info)</tag> @@ -434,6 +501,7 @@ typedef struct { const char* <em>name</em>; unsigned <em>arity</em>; ERL_NIF_TERM (*<em>fptr</em>)(ErlNifEnv* env, int argc, const ERL_NIF_TERM argv[]); + unsigned flags; } ErlNifFunc; </code> <p>Describes a NIF by its name, arity and implementation. @@ -444,7 +512,17 @@ typedef struct { will thus denote the Nth argument to the NIF. Note that the <c>argc</c> argument allows for the same C function to implement several Erlang functions with different arity (but - same name probably).</p> + same name probably). For a regular NIF, <c>flags</c> is 0 (and + so its value can be omitted for statically initialized <c>ErlNifFunc</c> + instances), or it can be used to indicate that the NIF is a <seealso + marker="#dirty_nifs">dirty NIF</seealso> that should be executed + on a dirty scheduler thread (<em>note that the dirty NIF functionality + described here is experimental</em> and that you have to enable + support for dirty schedulers when building OTP in order to try the + functionality out). If the dirty NIF is expected to be + CPU-bound, its <c>flags</c> field should be set to + <c>ERL_NIF_DIRTY_JOB_CPU_BOUND</c>, or for I/O-bound jobs, + <c>ERL_NIF_DIRTY_JOB_IO_BOUND</c>.</p> </item> <tag><marker id="ErlNifBinary"/>ErlNifBinary</tag> <item> @@ -775,6 +853,20 @@ typedef enum { Erlang operators <c>=:=</c> and <c>=/=</c>.</p></desc> </func> + <func><name><ret>int</ret><nametext>enif_is_on_dirty_scheduler(ErlNifEnv* env)</nametext></name> + <fsummary>Check to see if executing on a dirty scheduler thread</fsummary> + <desc> + <p>Check to see if the current NIF is executing on a dirty scheduler thread. If the + emulator is built with threading support, calling <c>enif_is_on_dirty_scheduler</c> + from within a dirty NIF returns true. It returns false when the calling NIF is a regular + NIF running on a normal scheduler thread, or when the emulator is built without threading + support.</p> + <note><p>This function is available only when the emulator is configured with dirty + schedulers enabled. This feature is currently disabled by default. To determine whether + the dirty NIF API is available, native code can check to see if the C preprocessor macro + <c>ERL_NIF_DIRTY_SCHEDULER_SUPPORT</c> is defined.</p></note> + </desc> + </func> <func><name><ret>int</ret><nametext>enif_is_pid(ErlNifEnv* env, ERL_NIF_TERM term)</nametext></name> <fsummary>Determine if a term is a pid</fsummary> <desc><p>Return true if <c>term</c> is a pid.</p></desc> @@ -1139,6 +1231,31 @@ typedef enum { <desc><p>Same as <seealso marker="erl_driver#erl_drv_rwlock_tryrwlock">erl_drv_rwlock_tryrwlock</seealso>. </p></desc> </func> + <func><name><ret>ERL_NIF_TERM</ret><nametext>enif_schedule_nif(ErlNifEnv* env, const char* fun_name, int flags, ERL_NIF_TERM (*fp)(ErlNifEnv* env, int argc, const ERL_NIF_TERM argv[]), int argc, const ERL_NIF_TERM argv[])</nametext></name> + <fsummary>Schedule a NIF for execution</fsummary> + <desc> + <p>Schedule NIF <c>fp</c> to execute. This function allows an application to break up long-running + work into multiple regular NIF calls or to schedule a <seealso marker="#dirty_nifs">dirty NIF</seealso> + to execute on a dirty scheduler thread (<em>note that the dirty NIF functionality described here is + experimental</em> and that you have to enable support for dirty schedulers when building OTP in + order to try the functionality out).</p> + <p>The <c>fun_name</c> argument provides a name for the NIF being scheduled for execution. If it cannot + be converted to an atom, <c>enif_schedule_nif</c> returns a <c>badarg</c> exception.</p> + <p>The <c>flags</c> argument must be set to 0 for a regular NIF, or if the emulator was built the + experimental dirty scheduler support enabled, <c>flags</c> can be set to either <c>ERL_NIF_DIRTY_JOB_CPU_BOUND</c> + if the job is expected to be primarily CPU-bound, or <c>ERL_NIF_DIRTY_JOB_IO_BOUND</c> for jobs that will + be I/O-bound. If dirty scheduler threads are not available in the emulator, a try to schedule such a job + will result in a <c>badarg</c> exception.</p> + + <p>The <c>argc</c> and <c>argv</c> arguments can either be the originals passed into the calling NIF, or + they can be values created by the calling NIF.</p> + <p>The calling NIF must use the return value of <c>enif_schedule_nif</c> as its own return value.</p> + <p>Be aware that <c>enif_schedule_nif</c>, as its name implies, only schedules the + NIF for future execution. The calling NIF does not block waiting for the scheduled NIF to + execute and return, which means that the calling NIF can't expect to receive the scheduled NIF + return value and use it for further operations.</p> + </desc> + </func> <func><name><ret>ErlNifPid *</ret><nametext>enif_self(ErlNifEnv* caller_env, ErlNifPid* pid)</nametext></name> <fsummary>Get the pid of the calling process.</fsummary> <desc><p>Initialize the pid variable <c>*pid</c> to represent the @@ -1236,4 +1353,3 @@ typedef enum { <p><seealso marker="erlang#load_nif-2">erlang:load_nif/2</seealso></p> </section> </cref> - diff --git a/erts/doc/src/erl_prim_loader.xml b/erts/doc/src/erl_prim_loader.xml index 9f5b3f385b..171f84decc 100644 --- a/erts/doc/src/erl_prim_loader.xml +++ b/erts/doc/src/erl_prim_loader.xml @@ -1,10 +1,10 @@ -<?xml version="1.0" encoding="latin1" ?> +<?xml version="1.0" encoding="utf-8" ?> <!DOCTYPE erlref SYSTEM "erlref.dtd"> <erlref> <header> <copyright> - <year>1996</year><year>2011</year> + <year>1996</year><year>2013</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -148,6 +148,22 @@ </desc> </func> <func> + <name name="read_link_info" arity="1"/> + <fsummary>Get information about a link or file</fsummary> + <desc> + <p>This function works like + <seealso marker="#read_file_info/1">read_file_info/1</seealso> + except that if <c><anno>Filename</anno></c> is a symbolic link, + information about the link will be returned in the <c>file_info</c> + record and the <c>type</c> field of the record will be set to + <c>symlink</c>.</p> + <p>If <c><anno>Filename</anno></c> is not a symbolic link, this function + returns exactly the same result as <c>read_file_info/1</c>. + On platforms that do not support symbolic links, this function + is always equivalent to <c>read_file_info/1</c>.</p> + </desc> + </func> + <func> <name name="set_path" arity="1"/> <fsummary>Set the path of the loader</fsummary> <desc> diff --git a/erts/doc/src/erlang.xml b/erts/doc/src/erlang.xml index 767edc1cc0..0e5909a52d 100644 --- a/erts/doc/src/erlang.xml +++ b/erts/doc/src/erlang.xml @@ -1,4 +1,4 @@ -<?xml version="1.0" encoding="latin1" ?> +<?xml version="1.0" encoding="utf-8" ?> <!DOCTYPE erlref SYSTEM "erlref.dtd"> <erlref> @@ -235,7 +235,7 @@ <code> 1> Bin = <<1,2,3,4,5,6,7,8,9,10>>. -2> binary_part(Bin,{byte_size(Bin), -5)). +2> binary_part(Bin,{byte_size(Bin), -5}). <<6,7,8,9,10>> </code> @@ -501,16 +501,87 @@ <name name="check_process_code" arity="2"/> <fsummary>Check if a process is executing old code for a module</fsummary> <desc> - <p>Returns <c>true</c> if the process <c><anno>Pid</anno></c> is executing - old code for <c><anno>Module</anno></c>. That is, if the current call of - the process executes old code for this module, or if the - process has references to old code for this module, or if the - process contains funs that references old code for this - module. Otherwise, it returns <c>false</c>.</p> - <pre> -> <input>check_process_code(Pid, lists).</input> -false</pre> + <p>The same as + <seealso marker="#check_process_code/3"><c>erlang:check_process_code(<anno>Pid</anno>, + <anno>Module</anno>, [])</c></seealso>.</p> + </desc> + </func> + <func> + <name name="check_process_code" arity="3"/> + <fsummary>Check if a process is executing old code for a module</fsummary> + <desc> + <p>Check if the node local process identified by <c><anno>Pid</anno></c> + is executing old code for <c><anno>Module</anno></c>.</p> + <p>Currently available <c><anno>Option</anno>s</c>:</p> + <taglist> + <tag><c>{allow_gc, boolean()}</c></tag> + <item> + Determines if garbage collection is allowed when performing + the operation. If <c>{allow_gc, false}</c> is passed, and + a garbage collection is needed in order to determine the + result of the operation, the operation will be aborted + (see information on <c><anno>CheckResult</anno></c> below). + The default is to allow garbage collection, i.e., + <c>{allow_gc, true}</c>. + </item> + <tag><c>{async, RequestId}</c></tag> + <item> + The <c>check_process_code/3</c> function will return + the value <c>async</c> immediately after the request + has been sent. When the request has been processed, the + process that called this function will be passed a + message on the form:<br/> + <c>{check_process_code, <anno>RequestId</anno>, <anno>CheckResult</anno>}</c>. + </item> + </taglist> + <p>If <c><anno>Pid</anno></c> equals <c>self()</c>, and + no <c>async</c> option has been passed, the operation will + be performed at once. In all other cases a request for + the operation will be sent to the process identified by + <c><anno>Pid</anno></c>, and will be handled when + appropriate. If no <c>async</c> option has been passed, + the caller will block until <c><anno>CheckResult</anno></c> + is available and can be returned.</p> + <p><c><anno>CheckResult</anno></c> informs about the result of + the request:</p> + <taglist> + <tag><c>true</c></tag> + <item> + The process identified by <c><anno>Pid</anno></c> is + executing old code for <c><anno>Module</anno></c>. + That is, the current call of the process executes old + code for this module, or the process has references + to old code for this module, or the process contains + funs that references old code for this module. + </item> + <tag><c>false</c></tag> + <item> + The process identified by <c><anno>Pid</anno></c> is + not executing old code for <c><anno>Module</anno></c>. + </item> + <tag><c>aborted</c></tag> + <item> + The operation was aborted since the process needed to + be garbage collected in order to determine the result + of the operation, and the operation was requested + by passing the <c>{allow_gc, false}</c> option.</item> + </taglist> <p>See also <seealso marker="kernel:code">code(3)</seealso>.</p> + <p>Failures:</p> + <taglist> + <tag><c>badarg</c></tag> + <item> + If <c><anno>Pid</anno></c> is not a node local process identifier. + </item> + <tag><c>badarg</c></tag> + <item> + If <c><anno>Module</anno></c> is not an atom. + </item> + <tag><c>badarg</c></tag> + <item> + If <c><anno>OptionList</anno></c> is not a valid list of options. + </item> + </taglist> </desc> </func> <func> @@ -816,7 +887,7 @@ false</pre> <fsummary>Print a term on standard output</fsummary> <desc> <p>Prints a text representation of <c><anno>Term</anno></c> on the standard - output.</p> + output. On OSE the term is printed to the ramlog.</p> <warning> <p>This BIF is intended for debugging only.</p> </warning> @@ -1197,20 +1268,74 @@ true that the spontaneous garbage collection will occur too late or not at all. Improper use may seriously degrade system performance.</p> - <p>Compatibility note: In versions of OTP prior to R7, - the garbage collection took place at the next context switch, - not immediately. To force a context switch after a call to - <c>erlang:garbage_collect()</c>, it was sufficient to make - any function call.</p> </desc> </func> <func> <name name="garbage_collect" arity="1"/> - <fsummary>Force an immediate garbage collection of a process</fsummary> + <fsummary>Garbage collect a process</fsummary> <desc> - <p>Works like <c>erlang:garbage_collect()</c> but on any - process. The same caveats apply. Returns <c>false</c> if - <c><anno>Pid</anno></c> refers to a dead process; <c>true</c> otherwise.</p> + <p>The same as + <seealso marker="#garbage_collect/2"><c>garbage_collect(<anno>Pid</anno>, [])</c></seealso>.</p> + </desc> + </func> + <func> + <name name="garbage_collect" arity="2"/> + <fsummary>Garbage collect a process</fsummary> + <desc> + <p>Garbage collect the node local process identified by + <c><anno>Pid</anno></c>.</p> + <p>Currently available <c><anno>Option</anno></c>s:</p> + <taglist> + <tag><c>{async, RequestId}</c></tag> + <item> + The <c>garbage_collect/2</c> function will return + the value <c>async</c> immediately after the request + has been sent. When the request has been processed, the + process that called this function will be passed a + message on the form:<br/> + <c>{garbage_collect, <anno>RequestId</anno>, <anno>GCResult</anno>}</c>. + </item> + </taglist> + <p>If <c><anno>Pid</anno></c> equals <c>self()</c>, and + no <c>async</c> option has been passed, the garbage + collection will be performed at once, i.e. the same as + calling + <seealso marker="#garbage_collect/0">garbage_collect/0</seealso>. + In all other cases a request for garbage collection will + be sent to the process identified by <c><anno>Pid</anno></c>, + and will be handled when appropriate. If no <c>async</c> + option has been passed, the caller will block until + <c><anno>GCResult</anno></c> is available and can be + returned.</p> + <p><c><anno>GCResult</anno></c> informs about the result of + the garbage collection request:</p> + <taglist> + <tag><c>true</c></tag> + <item> + The process identified by <c><anno>Pid</anno></c> has + been garbage collected. + </item> + <tag><c>false</c></tag> + <item> + No garbage collection was performed. This since the + the process identified by <c><anno>Pid</anno></c> + terminated before the request could be satisfied. + </item> + </taglist> + <p>Note that the same caveats as for + <seealso marker="#garbage_collect/0">garbage_collect/0</seealso> + apply.</p> + <p>Failures:</p> + <taglist> + <tag><c>badarg</c></tag> + <item> + If <c><anno>Pid</anno></c> is not a node local process identifier. + </item> + <tag><c>badarg</c></tag> + <item> + If <c><anno>OptionList</anno></c> is not a valid list of options. + </item> + </taglist> </desc> </func> <func> @@ -1231,7 +1356,7 @@ true <name name="get" arity="1"/> <fsummary>Return a value from the process dictionary</fsummary> <desc> - <p>Returns the value <c><anno>Val</anno></c>associated with <c><anno>Key</anno></c> in + <p>Returns the value <c><anno>Val</anno></c> associated with <c><anno>Key</anno></c> in the process dictionary, or <c>undefined</c> if <c><anno>Key</anno></c> does not exist.</p> <pre> @@ -1659,6 +1784,15 @@ os_prompt% </pre> </desc> </func> <func> + <name name="is_map" arity="1"/> + <fsummary>Check whether a term is a map</fsummary> + <desc> + <p>Returns <c>true</c> if <c><anno>Term</anno></c> is a map; + otherwise returns <c>false</c>.</p> + <p>Allowed in guard tests.</p> + </desc> + </func> + <func> <name name="is_number" arity="1"/> <fsummary>Check whether a term is a number</fsummary> <desc> @@ -2095,6 +2229,17 @@ os_prompt% </pre> </desc> </func> <func> + <name name="map_size" arity="1"/> + <fsummary>Return the size of a map</fsummary> + <desc> + <p>Returns an integer which is the number of key-value pairs in <c><anno>Map</anno></c>.</p> + <pre> +> <input>map_size(#{a=>1, b=>2, c=>3}).</input> +3</pre> + <p>Allowed in guard tests.</p> + </desc> + </func> + <func> <name name="max" arity="2"/> <fsummary>Return the largest of two term</fsummary> <desc> @@ -2467,7 +2612,7 @@ os_prompt% </pre> fails, a <c>nodedown</c> message is delivered.</p> <p>Nodes connected through hidden connections can be monitored as any other node.</p> - <p>Failure: <c>badarg</c>if the local node is not alive.</p> + <p>Failure: <c>badarg</c> if the local node is not alive.</p> </desc> </func> <func> @@ -2613,7 +2758,28 @@ os_prompt% </pre> <desc> <p>Returns a port identifier as the result of opening a new Erlang port. A port can be seen as an external Erlang - process. <c><anno>PortName</anno></c> is one of the following:</p> + process. + </p> + <p>The name of the executable as well as the arguments + given in <c>cd</c>, <c>env</c>, <c>args</c> and <c>arg0</c> is subject to + Unicode file name translation if the system is running + in Unicode file name mode. To avoid + translation or force i.e. UTF-8, supply the executable + and/or arguments as a binary in the correct + encoding. See the <seealso + marker="kernel:file">file</seealso> module, the + <seealso marker="kernel:file#native_name_encoding/0"> + file:native_name_encoding/0</seealso> function and the + <seealso marker="stdlib:unicode_usage">stdlib users guide + </seealso> for details.</p> + + <note><p>The characters in the name (if given as a list) + can only be > 255 if the Erlang VM is started in + Unicode file name translation mode, otherwise the name + of the executable is limited to the ISO-latin-1 + character set.</p></note> + + <p><c><anno>PortName</anno></c> is one of the following:</p> <taglist> <tag><c>{spawn, <anno>Command</anno>}</c></tag> <item> @@ -2668,32 +2834,13 @@ os_prompt% </pre> executed, the appropriate command interpreter will implicitly be invoked, but there will still be no command argument expansion or implicit PATH search.</p> - - <p>The name of the executable as well as the arguments - given in <c>args</c> and <c>arg0</c> is subject to - Unicode file name translation if the system is running - in Unicode file name mode. To avoid - translation or force i.e. UTF-8, supply the executable - and/or arguments as a binary in the correct - encoding. See the <seealso - marker="kernel:file">file</seealso> module, the - <seealso marker="kernel:file#native_name_encoding/0"> - file:native_name_encoding/0</seealso> function and the - <seealso marker="stdlib:unicode_usage">stdlib users guide - </seealso> for details.</p> - - <note><p>The characters in the name (if given as a list) - can only be > 255 if the Erlang VM is started in - Unicode file name translation mode, otherwise the name - of the executable is limited to the ISO-latin-1 - character set.</p></note> <p>If the <c><anno>FileName</anno></c> cannot be run, an error exception, with the posix error code as the reason, is raised. The error reason may differ between operating systems. Typically the error <c>enoent</c> is raised when one tries to run a program that is not found and - <c>eaccess</c> is raised when the given file is not + <c>eacces</c> is raised when the given file is not executable.</p> </item> <tag><c>{fd, <anno>In</anno>, <anno>Out</anno>}</c></tag> @@ -2762,11 +2909,7 @@ os_prompt% </pre> strings. The one exception is <c><anno>Val</anno></c> being the atom <c>false</c> (in analogy with <c>os:getenv/1</c>), which removes the environment variable. - </p> - <p>If Unicode filename encoding is in effect (see the <seealso - marker="erts:erl#file_name_encoding">erl manual - page</seealso>), the strings (both <c>Name</c> and - <c>Value</c>) may contain characters with codepoints > 255.</p> + </p> </item> <tag><c>{args, [ string() | binary() ]}</c></tag> <item> @@ -2794,21 +2937,6 @@ os_prompt% </pre> should not be given in this list. The proper executable name will automatically be used as argv[0] where applicable.</p> - <p>When the Erlang VM is running in Unicode file name - mode, the arguments can contain any Unicode characters and - will be translated into whatever is appropriate on the - underlying OS, which means UTF-8 for all platforms except - Windows, which has other (more transparent) ways of - dealing with Unicode arguments to programs. To avoid - Unicode translation of arguments, they can be supplied as - binaries in whatever encoding is deemed appropriate.</p> - - <note><p>The characters in the arguments (if given as a - list of characters) can only be > 255 if the Erlang - VM is started in Unicode file name mode, - otherwise the arguments are limited to the - ISO-latin-1 character set.</p></note> - <p>If one, for any reason, wants to explicitly set the program name in the argument vector, the <c>arg0</c> option can be used.</p> @@ -2824,9 +2952,6 @@ os_prompt% </pre> responds to this is highly system dependent and no specific effect is guaranteed.</p> - <p>The unicode file name translation rules of the - <c>args</c> option apply to this option as well.</p> - </item> <tag><c>exit_status</c></tag> @@ -2906,11 +3031,11 @@ os_prompt% </pre> <tag><marker id="open_port_parallelism"><c>{parallelism, Boolean}</c></marker></tag> <item> <p>Set scheduler hint for port parallelism. If set to <c>true</c>, - the VM will schedule port tasks when it by this can improve the + the VM will schedule port tasks when doing so will improve parallelism in the system. If set to <c>false</c>, the VM will - try to perform port tasks immediately and by this improving the - latency at the expense of parallelism. The default can be set on - system startup by passing the + try to perform port tasks immediately, improving latency at the + expense of parallelism. The default can be set on system startup + by passing the <seealso marker="erl#+spp">+spp</seealso> command line argument to <seealso marker="erl">erl(1)</seealso>. </p> @@ -3032,7 +3157,10 @@ os_prompt% </pre> (see below), being synchronous, and that the port does <em>not</em> reply with <c>{Port, closed}</c>. Any process may close a port with <c>port_close/1</c>, not only the port owner - (the connected process).</p> + (the connected process). If the calling process is linked to + port identified by <c><anno>Port</anno></c>, an exit signal due + to that link will be received by the process prior to the return + from <c>port_close/1</c>.</p> <p>For comparison: <c><anno>Port</anno> ! {self(), close}</c> fails with <c>badarg</c> if <c><anno>Port</anno></c> cannot be sent to (i.e., <c><anno>Port</anno></c> refers neither to a port nor to a process). If @@ -3041,6 +3169,7 @@ os_prompt% </pre> the port replies with <c>{Port, closed}</c> when all buffers have been flushed and the port really closes, but if the calling process is not the port owner the <em>port owner</em> fails with <c>badsig</c>.</p> + <p>Note that any process can close a port using <c><anno>Port</anno> ! {PortOwner, close}</c> just as if it itself was the port owner, but the reply always goes to the port owner.</p> @@ -3050,8 +3179,17 @@ os_prompt% </pre> implementation has been synchronous. <c>port_close/1</c> is however still fully synchronous. This due to its error behavior.</p> - <p>Failure: <c>badarg</c> if <c><anno>Port</anno></c> is not an open port or - the registered name of an open port.</p> + <p>Failure:</p> + <taglist> + <tag><c>badarg</c></tag> + <item> + If <c><anno>Port</anno></c> is not an identifier of an open + port, or the registered name of an open port. If the calling + process was linked to the previously open port identified by + <c><anno>Port</anno></c>, an exit signal due to this link + was received by the process prior to this exception. + </item> + </taglist> </desc> </func> <func> @@ -3086,8 +3224,11 @@ os_prompt% </pre> <taglist> <tag><c>badarg</c></tag> <item> - If <c><anno>Port</anno></c> is not an open port or the registered name - of an open port. + If <c><anno>Port</anno></c> is not an identifier of an open + port, or the registered name of an open port. If the calling + process was linked to the previously open port identified by + <c><anno>Port</anno></c>, an exit signal due to this link + was received by the process prior to this exception. </item> <tag><c>badarg</c></tag> <item> @@ -3130,8 +3271,11 @@ os_prompt% </pre> <taglist> <tag><c>badarg</c></tag> <item> - If <c><anno>Port</anno></c> is not an open port or the registered name - of an open port. + If <c><anno>Port</anno></c> is not an identifier of an open + port, or the registered name of an open port. If the calling + process was linked to the previously open port identified by + <c><anno>Port</anno></c>, an exit signal due to this link + was received by the process prior to this exception. </item> <tag><c>badarg</c></tag> <item> @@ -3198,9 +3342,20 @@ os_prompt% </pre> implementation has been synchronous. <c>port_connect/2</c> is however still fully synchronous. This due to its error behavior.</p> - <p>Failure: <c>badarg</c> if <c><anno>Port</anno></c> is not an open port - or the registered name of an open port, or if <c>Pid</c> is - not an existing local pid.</p> + <p>Failures:</p> + <taglist> + <tag><c>badarg</c></tag> + <item> + If <c><anno>Port</anno></c> is not an identifier of an open + port, or the registered name of an open port. If the calling + process was linked to the previously open port identified by + <c><anno>Port</anno></c>, an exit signal due to this link + was received by the process prior to this exception. + </item> + <tag><c>badarg</c></tag> + <item>If process identified by <c>Pid</c> is not an existing + local process.</item> + </taglist> </desc> </func> <func> @@ -3236,12 +3391,33 @@ os_prompt% </pre> binary term format and sent to the port.</p> <p>Returns: a term from the driver. The meaning of the returned data also depends on the port driver.</p> - <p>Failure: <c>badarg</c> if <c><anno>Port</anno></c> is not an open port or - the registered name of an open port, if <c><anno>Operation</anno></c> - cannot fit in a 32-bit integer, if the port driver does not - support synchronous control operations, or if the port driver - so decides for any reason (probably something wrong with - <c><anno>Operation</anno></c> or <c><anno>Data</anno></c>).</p> + <p>Failures:</p> + <taglist> + <tag><c>badarg</c></tag> + <item> + If <c><anno>Port</anno></c> is not an identifier of an open + port, or the registered name of an open port. If the calling + process was linked to the previously open port identified by + <c><anno>Port</anno></c>, an exit signal due to this link + was received by the process prior to this exception. + </item> + <tag><c>badarg</c></tag> + <item> + If <c><anno>Operation</anno></c> does not fit in a + 32-bit integer. + </item> + <tag><c>badarg</c></tag> + <item> + If the port driver does not support synchronous control + operations. + </item> + <tag><c>badarg</c></tag> + <item> + If the port driver so decides for any reason (probably + something wrong with <c><anno>Operation</anno></c>, or + <c><anno>Data</anno></c>). + </item> + </taglist> </desc> </func> <func> @@ -3251,7 +3427,12 @@ os_prompt% </pre> <p>Returns a list containing tuples with information about the <c><anno>Port</anno></c>, or <c>undefined</c> if the port is not open. The order of the tuples is not defined, nor are all the - tuples mandatory.</p> + tuples mandatory. + If <c>undefined</c> is returned and the calling process + was linked to a previously open port identified by + <c><anno>Port</anno></c>, an exit signal due to this link + was received by the process prior to the return from + <c>port_info/1</c>.</p> <p>Currently the result will containt information about the following <c>Item</c>s: <c>registered_name</c> (if the port has a registered name), <c>id</c>, <c>connected</c>, <c>links</c>, @@ -3269,7 +3450,11 @@ os_prompt% </pre> <p><c><anno>Pid</anno></c> is the process identifier of the process connected to the port.</p> <p>If the port identified by <c><anno>Port</anno></c> is not open, - <c>undefined</c> is returned.</p> + <c>undefined</c> is returned. If <c>undefined</c> is returned and + the calling process was linked to a previously open port identified + by <c><anno>Port</anno></c>, an exit signal due to this link + was received by the process prior to the return from + <c>port_info/2</c>.</p> <p>Failure: <c>badarg</c> if <c><anno>Port</anno></c> is not a local port identifier, or an atom.</p> </desc> @@ -3281,7 +3466,11 @@ os_prompt% </pre> <p><c><anno>Index</anno></c> is the internal index of the port. This index may be used to separate ports.</p> <p>If the port identified by <c><anno>Port</anno></c> is not open, - <c>undefined</c> is returned.</p> + <c>undefined</c> is returned. If <c>undefined</c> is returned and + the calling process was linked to a previously open port identified + by <c><anno>Port</anno></c>, an exit signal due to this link + was received by the process prior to the return from + <c>port_info/2</c>.</p> <p>Failure: <c>badarg</c> if <c><anno>Port</anno></c> is not a local port identifier, or an atom.</p> </desc> @@ -3293,7 +3482,11 @@ os_prompt% </pre> <p><c><anno>Bytes</anno></c> is the total number of bytes read from the port.</p> <p>If the port identified by <c><anno>Port</anno></c> is not open, - <c>undefined</c> is returned.</p> + <c>undefined</c> is returned. If <c>undefined</c> is returned and + the calling process was linked to a previously open port identified + by <c><anno>Port</anno></c>, an exit signal due to this link + was received by the process prior to the return from + <c>port_info/2</c>.</p> <p>Failure: <c>badarg</c> if <c><anno>Port</anno></c> is not a local port identifier, or an atom.</p> </desc> @@ -3305,7 +3498,11 @@ os_prompt% </pre> <p><c><anno>Pids</anno></c> is a list of the process identifiers of the processes that the port is linked to.</p> <p>If the port identified by <c><anno>Port</anno></c> is not open, - <c>undefined</c> is returned.</p> + <c>undefined</c> is returned. If <c>undefined</c> is returned and + the calling process was linked to a previously open port identified + by <c><anno>Port</anno></c>, an exit signal due to this link + was received by the process prior to the return from + <c>port_info/2</c>.</p> <p>Failure: <c>badarg</c> if <c><anno>Port</anno></c> is not a local port identifier, or an atom.</p> </desc> @@ -3320,7 +3517,11 @@ os_prompt% </pre> that these results are highly implementation specific and might change in the future.</p> <p>If the port identified by <c><anno>Port</anno></c> is not open, - <c>undefined</c> is returned.</p> + <c>undefined</c> is returned. If <c>undefined</c> is returned and + the calling process was linked to a previously open port identified + by <c><anno>Port</anno></c>, an exit signal due to this link + was received by the process prior to the return from + <c>port_info/2</c>.</p> <p>Failure: <c>badarg</c> if <c><anno>Port</anno></c> is not a local port identifier, or an atom.</p> </desc> @@ -3334,7 +3535,11 @@ os_prompt% </pre> that the port itself might have allocated memory which is not included in <c><anno>Bytes</anno></c>.</p> <p>If the port identified by <c><anno>Port</anno></c> is not open, - <c>undefined</c> is returned.</p> + <c>undefined</c> is returned. If <c>undefined</c> is returned and + the calling process was linked to a previously open port identified + by <c><anno>Port</anno></c>, an exit signal due to this link + was received by the process prior to the return from + <c>port_info/2</c>.</p> <p>Failure: <c>badarg</c> if <c><anno>Port</anno></c> is not a local port identifier, or an atom.</p> </desc> @@ -3346,7 +3551,11 @@ os_prompt% </pre> <p><c><anno>Monitors</anno></c> represent processes that this port is monitoring.</p> <p>If the port identified by <c><anno>Port</anno></c> is not open, - <c>undefined</c> is returned.</p> + <c>undefined</c> is returned. If <c>undefined</c> is returned and + the calling process was linked to a previously open port identified + by <c><anno>Port</anno></c>, an exit signal due to this link + was received by the process prior to the return from + <c>port_info/2</c>.</p> <p>Failure: <c>badarg</c> if <c><anno>Port</anno></c> is not a local port identifier, or an atom.</p> </desc> @@ -3358,7 +3567,11 @@ os_prompt% </pre> <p><c><anno>Name</anno></c> is the command name set by <seealso marker="#open_port/2">open_port/2</seealso>.</p> <p>If the port identified by <c><anno>Port</anno></c> is not open, - <c>undefined</c> is returned.</p> + <c>undefined</c> is returned. If <c>undefined</c> is returned and + the calling process was linked to a previously open port identified + by <c><anno>Port</anno></c>, an exit signal due to this link + was received by the process prior to the return from + <c>port_info/2</c>.</p> <p>Failure: <c>badarg</c> if <c><anno>Port</anno></c> is not a local port identifier, or an atom.</p> </desc> @@ -3373,7 +3586,11 @@ os_prompt% </pre> Command}, Options)</seealso>. If the port is not the result of spawning an OS process, the value is <c>undefined</c>.</p> <p>If the port identified by <c><anno>Port</anno></c> is not open, - <c>undefined</c> is returned.</p> + <c>undefined</c> is returned. If <c>undefined</c> is returned and + the calling process was linked to a previously open port identified + by <c><anno>Port</anno></c>, an exit signal due to this link + was received by the process prior to the return from + <c>port_info/2</c>.</p> <p>Failure: <c>badarg</c> if <c><anno>Port</anno></c> is not a local port identifier, or an atom.</p> </desc> @@ -3389,7 +3606,11 @@ os_prompt% </pre> or <c><anno>Port</anno> ! {Owner, {command, Data}</c>. </p> <p>If the port identified by <c><anno>Port</anno></c> is not open, - <c>undefined</c> is returned.</p> + <c>undefined</c> is returned. If <c>undefined</c> is returned and + the calling process was linked to a previously open port identified + by <c><anno>Port</anno></c>, an exit signal due to this link + was received by the process prior to the return from + <c>port_info/2</c>.</p> <p>Failure: <c>badarg</c> if <c><anno>Port</anno></c> is not a local port identifier, or an atom.</p> </desc> @@ -3412,7 +3633,11 @@ os_prompt% </pre> in bytes, queued by the port using the ERTS driver queue implementation.</p> <p>If the port identified by <c><anno>Port</anno></c> is not open, - <c>undefined</c> is returned.</p> + <c>undefined</c> is returned. If <c>undefined</c> is returned and + the calling process was linked to a previously open port identified + by <c><anno>Port</anno></c>, an exit signal due to this link + was received by the process prior to the return from + <c>port_info/2</c>.</p> <p>Failure: <c>badarg</c> if <c><anno>Port</anno></c> is not a local port identifier, or an atom.</p> </desc> @@ -3424,7 +3649,11 @@ os_prompt% </pre> <p><c><anno>RegisteredName</anno></c> is the registered name of the port. If the port has no registered name, <c>[]</c> is returned.</p> <p>If the port identified by <c><anno>Port</anno></c> is not open, - <c>undefined</c> is returned.</p> + <c>undefined</c> is returned. If <c>undefined</c> is returned and + the calling process was linked to a previously open port identified + by <c><anno>Port</anno></c>, an exit signal due to this link + was received by the process prior to the return from + <c>port_info/2</c>.</p> <p>Failure: <c>badarg</c> if <c><anno>Port</anno></c> is not a local port identifier, or an atom.</p> </desc> @@ -4613,6 +4842,8 @@ true</pre> <c><anno>Node</anno></c> does not exist, a useless pid is returned. Otherwise works like <seealso marker="#spawn_opt/4">spawn_opt/4</seealso>.</p> + <note><p>The <c>monitor</c> option is currently not supported by + <c>spawn_opt/5</c>.</p></note> </desc> </func> <func> @@ -4727,8 +4958,8 @@ true</pre> <name name="statistics" arity="1" clause_i="6"/> <fsummary>Information about the run-queue</fsummary> <desc> - <p>Returns the length of the run queue, that is, the number - of processes that are ready to run.</p> + <p>Returns the total length of the run queues, that is, the number + of processes that are ready to run on all available run queues.</p> </desc> </func> <func> @@ -4737,7 +4968,7 @@ true</pre> <desc> <p>Note that the run-time is the sum of the run-time for all threads in the Erlang run-time system and may therefore be greater - than the wall-clock time.</p> + than the wall-clock time. The time is returned in milliseconds.</p> <pre> > <input>statistics(runtime).</input> {1690,1620} @@ -4985,6 +5216,34 @@ ok </func> <func> <name name="system_flag" arity="2" clause_i="3"/> + <fsummary>Set system flag dirty CPU schedulers online</fsummary> + <desc> + <p><marker id="system_flag_dirty_cpu_schedulers_online"></marker> + Sets the amount of dirty CPU schedulers online. Valid range is + <![CDATA[1 <= DirtyCPUSchedulersOnline <= N]]> where <c>N</c> is the + lesser of the return values of <c>erlang:system_info(dirty_cpu_schedulers)</c> and + <c>erlang:system_info(schedulers_online)</c>. + </p> + <p>Returns the old value of the flag.</p> + <p>Note that the number of dirty CPU schedulers online may change if the number of + schedulers online changes. For example, if there are 12 schedulers and all are + online, and 6 dirty CPU schedulers, all online as well, and <c>system_flag/2</c> + is used to set the number of schedulers online to 6, then the number of dirty + CPU schedulers online is automatically decreased by half as well, down to 3. + Similarly, the number of dirty CPU schedulers online increases proportionally + to increases in the number of schedulers online.</p> + <p><em>Note that the dirty schedulers functionality is experimental</em>, and + that you have to enable support for dirty schedulers when building OTP in order + to try out the functionality.</p> + <p>For more information see + <seealso marker="#system_info_dirty_cpu_schedulers">erlang:system_info(dirty_cpu_schedulers)</seealso> + and + <seealso marker="#system_info_dirty_cpu_schedulers_online">erlang:system_info(dirty_cpu_schedulers_online)</seealso>. + </p> + </desc> + </func> + <func> + <name name="system_flag" arity="2" clause_i="4"/> <fsummary>Set system flag fullsweep_after</fsummary> <desc> <p><c><anno>Number</anno></c> is a non-negative integer which indicates @@ -5002,7 +5261,7 @@ ok </desc> </func> <func> - <name name="system_flag" arity="2" clause_i="4"/> + <name name="system_flag" arity="2" clause_i="5"/> <fsummary>Set system flag min_heap_size</fsummary> <desc> <p>Sets the default minimum heap size for processes. The @@ -5017,7 +5276,7 @@ ok </desc> </func> <func> - <name name="system_flag" arity="2" clause_i="5"/> + <name name="system_flag" arity="2" clause_i="6"/> <fsummary>Set system flag min_bin_vheap_size</fsummary> <desc> <p>Sets the default minimum binary virtual heap size for processes. The @@ -5032,7 +5291,7 @@ ok </desc> </func> <func> - <name name="system_flag" arity="2" clause_i="6"/> + <name name="system_flag" arity="2" clause_i="7"/> <fsummary>Set system flag multi_scheduling</fsummary> <desc> <p><marker id="system_flag_multi_scheduling"></marker> @@ -5070,7 +5329,7 @@ ok </desc> </func> <func> - <name name="system_flag" arity="2" clause_i="7"/> + <name name="system_flag" arity="2" clause_i="8"/> <type name="scheduler_bind_type"/> <fsummary>Set system flag scheduler_bind_type</fsummary> <desc> @@ -5190,7 +5449,7 @@ ok </desc> </func> <func> - <name name="system_flag" arity="2" clause_i="8"/> + <name name="system_flag" arity="2" clause_i="9"/> <fsummary>Set system flag scheduler_wall_time</fsummary> <desc><p><marker id="system_flag_scheduler_wall_time"></marker> Turns on/off scheduler wall time measurements. </p> @@ -5200,7 +5459,7 @@ ok </desc> </func> <func> - <name name="system_flag" arity="2" clause_i="9"/> + <name name="system_flag" arity="2" clause_i="10"/> <fsummary>Set system flag schedulers_online</fsummary> <desc> <p><marker id="system_flag_schedulers_online"></marker> @@ -5208,6 +5467,15 @@ ok <![CDATA[1 <= SchedulersOnline <= erlang:system_info(schedulers)]]>. </p> <p>Returns the old value of the flag.</p> + <p>Note that if the emulator was built with support for <seealso + marker="#system_flag_dirty_cpu_schedulers_online">dirty schedulers</seealso>, + changing the number of schedulers online can also change the number of dirty + CPU schedulers online. For example, if there are 12 schedulers and all are + online, and 6 dirty CPU schedulers, all online as well, and <c>system_flag/2</c> + is used to set the number of schedulers online to 6, then the number of dirty + CPU schedulers online is automatically decreased by half as well, down to 3. + Similarly, the number of dirty CPU schedulers online increases proportionally + to increases in the number of schedulers online.</p> <p>For more information see, <seealso marker="#system_info_schedulers">erlang:system_info(schedulers)</seealso>, and @@ -5216,7 +5484,7 @@ ok </desc> </func> <func> - <name name="system_flag" arity="2" clause_i="10"/> + <name name="system_flag" arity="2" clause_i="11"/> <fsummary>Set system flag trace_control_word</fsummary> <desc> <p>Sets the value of the node's trace control word to @@ -5316,7 +5584,11 @@ ok As of erts version 5.6.1 the return value is a list of <c>{instance, InstanceNo, InstanceInfo}</c> tuples where <c>InstanceInfo</c> contains information about - a specific instance of the allocator. + a specific instance of the allocator. As of erts version + 5.10.4 the returned list when calling + <c>erlang:system_info({allocator, mseg_alloc})</c> also + include an <c>{erts_mmap, _}</c> tuple as one element + in the list. If <c><anno>Alloc</anno></c> is not a recognized allocator, <c>undefined</c> is returned. If <c><anno>Alloc</anno></c> is disabled, <c>false</c> is returned.</p> @@ -5500,6 +5772,10 @@ ok <name name="system_info" arity="1" clause_i="49"/> <name name="system_info" arity="1" clause_i="50"/> <name name="system_info" arity="1" clause_i="51"/> + <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"/> <fsummary>Information about the system</fsummary> <desc> <p>Returns various information about the current system @@ -5569,6 +5845,72 @@ ok compiled; otherwise, <c>false</c>. </p> </item> + <tag><marker id="system_info_dirty_cpu_schedulers"><c>dirty_cpu_schedulers</c></marker></tag> + <item> + <p>Returns the number of dirty CPU scheduler threads used by + the emulator. Dirty CPU schedulers execute CPU-bound + native functions such as NIFs, linked-in driver code, and BIFs + that cannot be managed cleanly by the emulator's normal schedulers. + </p> + <p>The number of dirty CPU scheduler threads is determined at emulator + boot time and cannot be changed after that. The number of dirty CPU + scheduler threads online can however be changed at any time. The number of + dirty CPU schedulers can be set on startup by passing + the <seealso marker="erts:erl#+SDcpu">+SDcpu</seealso> or + <seealso marker="erts:erl#+SDPcpu">+SDPcpu</seealso> command line flags, + see <seealso marker="erts:erl#+SDcpu">erl(1)</seealso>. + </p> + <p><em>Note that the dirty schedulers functionality is experimental</em>, and + that you have to enable support for dirty schedulers when building OTP in + order to try out the functionality.</p> + <p>See also <seealso marker="#system_flag_dirty_cpu_schedulers_online">erlang:system_flag(dirty_cpu_schedulers_online, DirtyCPUSchedulersOnline)</seealso>, + <seealso marker="#system_info_dirty_cpu_schedulers_online">erlang:system_info(dirty_cpu_schedulers_online)</seealso>, + <seealso marker="#system_info_dirty_io_schedulers">erlang:system_info(dirty_io_schedulers)</seealso>, + <seealso marker="#system_info_schedulers">erlang:system_info(schedulers)</seealso>, + <seealso marker="#system_info_schedulers_online">erlang:system_info(schedulers_online)</seealso>, and + <seealso marker="#system_flag_schedulers_online">erlang:system_flag(schedulers_online, SchedulersOnline)</seealso>.</p> + </item> + <tag><marker id="system_info_dirty_cpu_schedulers_online"><c>dirty_cpu_schedulers_online</c></marker></tag> + <item> + <p>Returns the number of dirty CPU schedulers online. The return value + satisfies the following relationship: + <c><![CDATA[1 <= DirtyCPUSchedulersOnline <= N]]></c>, where <c>N</c> is + the lesser of the return values of <c>erlang:system_info(dirty_cpu_schedulers)</c> and + <c>erlang:system_info(schedulers_online)</c>. + </p> + <p>The number of dirty CPU schedulers online can be set on startup by passing + the <seealso marker="erts:erl#+SDcpu">+SDcpu</seealso> command line flag, see + <seealso marker="erts:erl#+SDcpu">erl(1)</seealso>. + </p> + <p><em>Note that the dirty schedulers functionality is experimental</em>, and + that you have to enable support for dirty schedulers when building OTP in + order to try out the functionality.</p> + <p>For more information, see + <seealso marker="#system_info_dirty_cpu_schedulers">erlang:system_info(dirty_cpu_schedulers)</seealso>, + <seealso marker="#system_info_dirty_io_schedulers">erlang:system_info(dirty_io_schedulers)</seealso>, + <seealso marker="#system_info_schedulers_online">erlang:system_info(schedulers_online)</seealso>, and + <seealso marker="#system_flag_dirty_cpu_schedulers_online">erlang:system_flag(dirty_cpu_schedulers_online, DirtyCPUSchedulersOnline)</seealso>. + </p> + </item> + <tag><marker id="system_info_dirty_io_schedulers"><c>dirty_io_schedulers</c></marker></tag> + <item> + <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 that + cannot be managed cleanly by the emulator's normal schedulers. + </p> + <p>This value can be set on startup by passing + the <seealso marker="erts:erl#+SDio">+SDio</seealso> command line flag, see + <seealso marker="erts:erl#+SDio">erl(1)</seealso>. + </p> + <p><em>Note that the dirty schedulers functionality is experimental</em>, and + that you have to enable support for dirty schedulers when building OTP in + order to try out the functionality.</p> + <p>For more information, see + <seealso marker="#system_info_dirty_cpu_schedulers">erlang:system_info(dirty_cpu_schedulers)</seealso>, + <seealso marker="#system_info_dirty_cpu_schedulers_online">erlang:system_info(dirty_cpu_schedulers_online)</seealso>, and + <seealso marker="#system_flag_dirty_cpu_schedulers_online">erlang:system_flag(dirty_cpu_schedulers_online, DirtyCPUSchedulersOnline)</seealso>. + </p> + </item> <tag><c>dist</c></tag> <item> <p>Returns a binary containing a string of distribution @@ -5576,6 +5918,13 @@ ok information see the <seealso marker="erts:crash_dump">"How to interpret the Erlang crash dumps"</seealso> chapter in the ERTS User's Guide.</p> </item> + <tag><marker id="system_info_dist_buf_busy_limit"><c>dist_buf_busy_limit</c></marker></tag> + <item> + <p>Returns the value of the distribution buffer busy limit + in bytes. This limit can be set on startup by passing the + <seealso marker="erts:erl#+zdbbl">+zdbbl</seealso> command line + flag to <c>erl</c>.</p> + </item> <tag><c>dist_ctrl</c></tag> <item> <p>Returns a list of tuples @@ -5622,12 +5971,24 @@ ok The return value will always be <c>false</c> since the elib_malloc allocator has been removed.</p> </item> - <tag><marker id="system_info_dist_buf_busy_limit"><c>dist_buf_busy_limit</c></marker></tag> + <tag><marker id="system_info_eager_check_io"><c>eager_check_io</c></marker></tag> <item> - <p>Returns the value of the distribution buffer busy limit - in bytes. This limit can be set on startup by passing the - <seealso marker="erts:erl#+zdbbl">+zdbbl</seealso> command line - flag to <c>erl</c>.</p> + <p> + Returns the value of the <c>erl</c> + <seealso marker="erl#+secio">+secio</seealso> command line + flag which is either <c>true</c> or <c>false</c>. See the + documentation of the command line flag for information about + the different values. + </p> + </item> + <tag><c>ets_limit</c></tag> + <item> + <p>Returns the maximum number of ETS tables allowed. This limit + can be increased on startup by passing the <seealso + marker="erts:erl#+e">+e</seealso> command line flag to + <c>erl</c> or by setting the environment variable + <c>ERL_MAX_ETS_TABLES</c> before starting the Erlang runtime + system.</p> </item> <tag><c>fullsweep_after</c></tag> <item> @@ -5783,9 +6144,24 @@ ok <seealso marker="#system_info_multi_scheduling">erlang:system_info(multi_scheduling)</seealso>, and <seealso marker="#system_info_schedulers">erlang:system_info(schedulers)</seealso>.</p> </item> + <tag><c>nif_version</c></tag> + <item> + <p>Returns a string containing the erlang NIF version + used by the runtime system. It will be on the form "<major ver>.<minor ver>".</p> + </item> <tag><marker id="system_info_otp_release"><c>otp_release</c></marker></tag> <item> - <p>Returns a string containing the OTP release number.</p> + <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 of OTP release 17, the OTP release number corresponds to + the major OTP version number. There is no + <c>erlang:system_info()</c> argument giving the exact OTP + version. This since the exact OTP version in the general case + is hard to determine. For more information see + <seealso marker="doc/system_principles:versions">the + documentation of versions in the system principles + guide</seealso>.</p> </item> <tag><marker id="system_info_port_parallelism"><c>port_parallelism</c></marker></tag> <item><p>Returns the default port parallelism scheduling hint used. @@ -5935,6 +6311,13 @@ ok (<seealso marker="erts:erl_driver#driver_async">driver_async()</seealso>) as an integer.</p> </item> + <tag><marker id="system_info_tolerant_timeofday"><c>tolerant_timeofday</c></marker></tag> + <item> + <p>Returns whether compensation for sudden changes of system + time is <c>enabled</c> or <c>disabled</c>.</p> + <p>See also <seealso marker="erts:erl#+c">+c</seealso> + command line flag.</p> + </item> <tag><c>trace_control_word</c></tag> <item> <p>Returns the value of the node's trace control word. @@ -6251,11 +6634,12 @@ ok some details of the encoding. This option was introduced in R11B-4. Currently, the allowed values for <c><anno>Version</anno></c> are <c>0</c> and <c>1</c>.</p> - <p><c>{minor_version, 1}</c> forces any floats in the term to be encoded + <p><c>{minor_version, 1}</c> is since 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). <c>binary_to_term/1</c> - in R11B-4 and later is able decode the new representation.</p> - <p><c>{minor_version, 0}</c> is currently the default, meaning that floats + in R11B-4 and later is able decode this representation.</p> + <p><c>{minor_version, 0}</c> meaning that floats will be encoded using a textual representation; this option is useful if you want to ensure that releases prior to R11B-4 can decode resulting binary.</p> diff --git a/erts/doc/src/erlc.xml b/erts/doc/src/erlc.xml index 81dffe45cf..c3fc3b1686 100644 --- a/erts/doc/src/erlc.xml +++ b/erts/doc/src/erlc.xml @@ -1,10 +1,10 @@ -<?xml version="1.0" encoding="latin1" ?> +<?xml version="1.0" encoding="utf-8" ?> <!DOCTYPE comref SYSTEM "comref.dtd"> <comref> <header> <copyright> - <year>1997</year><year>2012</year> + <year>1997</year><year>2013</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -234,6 +234,16 @@ erlc +export_all file.erl</pre> from the shell.</p> <p>Supported options: -I, -o, -D, -v, -W, -b.</p> </item> + <tag>.S</tag> + <item> + <p>Erlang assembler source code. It generates a <c><![CDATA[.beam]]></c> file.</p> + <p>Supported options: same as for .erl.</p> + </item> + <tag>.core</tag> + <item> + <p>Erlang core source code. It generates a <c><![CDATA[.beam]]></c> file.</p> + <p>Supported options: same as for .erl.</p> + </item> <tag>.yrl</tag> <item> <p>Yecc source code. It generates an <c><![CDATA[.erl]]></c> file.</p> diff --git a/erts/doc/src/erlsrv.xml b/erts/doc/src/erlsrv.xml index 365ae21d39..71cee714a5 100644 --- a/erts/doc/src/erlsrv.xml +++ b/erts/doc/src/erlsrv.xml @@ -1,10 +1,10 @@ -<?xml version="1.0" encoding="latin1" ?> +<?xml version="1.0" encoding="utf-8" ?> <!DOCTYPE comref SYSTEM "comref.dtd"> <comref> <header> <copyright> - <year>1998</year><year>2012</year> + <year>1998</year><year>2013</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> diff --git a/erts/doc/src/erts_alloc.xml b/erts/doc/src/erts_alloc.xml index 2ffb55c6ab..1ade41f1aa 100644 --- a/erts/doc/src/erts_alloc.xml +++ b/erts/doc/src/erts_alloc.xml @@ -1,10 +1,10 @@ -<?xml version="1.0" encoding="latin1" ?> +<?xml version="1.0" encoding="utf-8" ?> <!DOCTYPE cref SYSTEM "cref.dtd"> <cref> <header> <copyright> - <year>2002</year><year>2013</year> + <year>2002</year><year>2014</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -170,6 +170,15 @@ used. The time complexity is proportional to log N, where N is the number of free blocks.</p> </item> + <tag>Address order first fit carrier best fit</tag> + <item> + <p>Strategy: Find the <em>carrier</em> with the lowest address that + can satisfy the requested block size, then find a block within + that carrier using the "best fit" strategy.</p> + <p>Implementation: Balanced binary search trees are + used. The time complexity is proportional to log N, where + N is the number of free blocks.</p> + </item> <tag>Address order first fit carrier address order best fit</tag> <item> <p>Strategy: Find the <em>carrier</em> with the lowest address that @@ -262,6 +271,77 @@ memory segment cache is not reused if its size exceeds the requested size with more than relative max cache bad fit percent of the requested size. Default value is 20.</item> + <tag><marker id="MMsco"><c><![CDATA[+MMsco true|false]]></c></marker></tag> + <item> + Set <seealso marker="#MMscs">super carrier</seealso> only flag. This + flag defaults to <c>true</c>. When a super carrier is used and this + flag is <c>true</c>, <c>mseg_alloc</c> will only create carriers + in the super carrier. Note that the <c>alloc_util</c> framework may + create <c>sys_alloc</c> carriers, so if you want all carriers to + be created in the super carrier, you therefore want to disable use + of <c>sys_alloc</c> carriers by also passing + <seealso marker="#Musac"><c>+Musac false</c></seealso>. When the flag + is <c>false</c>, <c>mseg_alloc</c> will try to create carriers outside + of the super carrier when the super carrier is full. + <br/><br/> + <em>NOTE</em>: Setting this flag to <c>false</c> may not be supported + on all systems. This flag will in that case be ignored. + <br/><br/> + <em>NOTE</em>: The super carrier cannot be enabled nor + disabled on halfword heap systems. This flag will be + ignored on halfword heap systems. + </item> + <tag><marker id="MMscrfsd"><c><![CDATA[+MMscrfsd <amount>]]></c></marker></tag> + <item> + Set <seealso marker="#MMscs">super carrier</seealso> reserved + free segment descriptors. This parameter defaults to <c>65536</c>. + This parameter determines the amount of memory to reserve for + free segment descriptors used by the super carrier. If the system + runs out of reserved memory for free segment descriptors, other + memory will be used. This may however cause fragmentation issues, + so you want to ensure that this never happens. The maximum amount + of free segment descriptors used can be retrieved from the + <c>erts_mmap</c> tuple part of the result from calling + <seealso marker="erts:erlang#system_info_allocator_tuple">erlang:system_info({allocator, mseg_alloc})</seealso>. + </item> + <tag><marker id="MMscrpm"><c><![CDATA[+MMscrpm true|false]]></c></marker></tag> + <item> + Set <seealso marker="#MMscs">super carrier</seealso> reserve physical + memory flag. This flag defaults to <c>true</c>. When this flag is + <c>true</c>, physical memory will be reserved for the whole super + carrier at once when it is created. The reservation will after that + be left unchanged. When this flag is set to <c>false</c> only virtual + address space will be reserved for the super carrier upon creation. + The system will attempt to reserve physical memory upon carrier + creations in the super carrier, and attempt to unreserve physical + memory upon carrier destructions in the super carrier. + <br/><br/> + <em>NOTE</em>: What reservation of physical memory actually means + highly depends on the operating system, and how it is configured. For + example, different memory overcommit settings on Linux drastically + change the behaviour. Also note, setting this flag to <c>false</c> + may not be supported on all systems. This flag will in that case + be ignored. + <br/><br/> + <em>NOTE</em>: The super carrier cannot be enabled nor + disabled on halfword heap systems. This flag will be + ignored on halfword heap systems. + </item> + <tag><marker id="MMscs"><c><![CDATA[+MMscs <size in MB>]]></c></marker></tag> + <item> + Set super carrier size (in MB). The super carrier size defaults to + zero; i.e, the super carrier is by default disabled. The super + carrier is a large continuous area in the virtual address space. + <c>mseg_alloc</c> will always try to create new carriers in the super + carrier if it exists. Note that the <c>alloc_util</c> framework may + create <c>sys_alloc</c> carriers. For more information on this, see the + documentation of the <seealso marker="#MMsco"><c>+MMsco</c></seealso> + flag. + <br/><br/> + <em>NOTE</em>: The super carrier cannot be enabled nor + disabled on halfword heap systems. This flag will be + ignored on halfword heap systems. + </item> <tag><marker id="MMmcs"><c><![CDATA[+MMmcs <amount>]]></c></marker></tag> <item> Max cached segments. The maximum number of memory segments @@ -315,35 +395,37 @@ <c><![CDATA[<utilization>]]></c> is an integer in the range <c>[0, 100]</c> representing utilization in percent. When a utilization value larger than zero is used, allocator instances - are allowed to abandon multiblock carriers. Currently the default - is zero. If <c>de</c> (default enabled) is passed instead of a - <c><![CDATA[<utilization>]]></c>, a recomended non zero utilization - value will be used. The actual value chosen depend on allocator - type and may be changed between ERTS versions. Carriers will be - abandoned when memory utilization in the allocator instance falls - below the utilization value used. Once a carrier has been abandoned, - no new allocations will be made in it. When an allocator instance - gets an increased multiblock carrier need, it will first try to - fetch an abandoned carrier from an allocator instances of the same + are allowed to abandon multiblock carriers. If <c>de</c> (default + enabled) is passed instead of a <c><![CDATA[<utilization>]]></c>, + a recomended non zero utilization value will be used. The actual + value chosen depend on allocator type and may be changed between + ERTS versions. Currently the default equals <c>de</c>, but this + may be changed in the future. Carriers will be abandoned when + memory utilization in the allocator instance falls below the + utilization value used. Once a carrier has been abandoned, no new + allocations will be made in it. When an allocator instance gets an + increased multiblock carrier need, it will first try to fetch an + abandoned carrier from an allocator instances of the same allocator type. If no abandoned carrier could be fetched, it will create a new empty carrier. When an abandoned carrier has been fetched it will function as an ordinary carrier. This feature has special requirements on the <seealso marker="#M_as">allocation strategy</seealso> used. Currently - only the <c>aoff</c> and the <c>aoffcaobf</c> strategies support + only the strategies <c>aoff</c>, <c>aoffcbf</c> and <c>aoffcaobf</c> support abandoned carriers. This feature also requires <seealso marker="#M_t">multiple thread specific instances</seealso> to be enabled. When enabling this feature, multiple thread specific instances will be enabled if not already enabled, and the - <c>aoffcaobf</c> strategy will be enabled if current strategy does not + <c>aoffcbf</c> strategy will be enabled if current strategy does not support abandoned carriers. This feature can be enabled on all allocators based on the <c>alloc_util</c> framework with the exception of <c>temp_alloc</c> (which would be pointless). </item> - <tag><marker id="M_as"><c><![CDATA[+M<S>as bf|aobf|aoff|aoffcaobf|gf|af]]></c></marker></tag> + <tag><marker id="M_as"><c><![CDATA[+M<S>as bf|aobf|aoff|aoffcbf|aoffcaobf|gf|af]]></c></marker></tag> <item> Allocation strategy. Valid strategies are <c>bf</c> (best fit), <c>aobf</c> (address order best fit), <c>aoff</c> (address order first fit), + <c>aoffcbf</c> (address order first fit carrier best fit), <c>aoffcaobf</c> (address order first fit carrier address order best fit), <c>gf</c> (good fit), and <c>af</c> (a fit). See <seealso marker="#strategy">the description of allocation strategies</seealso> in "the <c>alloc_util</c> framework" section.</item> @@ -449,15 +531,9 @@ <p>Multiple, thread specific instances of the allocator. This option will only have any effect on the runtime system with SMP support. Default behaviour on the runtime system with - SMP support:</p> - <taglist> - <tag><c>ll_alloc</c></tag> - <item><c>1</c> instance.</item> - <tag>Other allocators</tag> - <item><c>NoSchedulers+1</c> instances. Each scheduler will use - a lock-free instance of its own and other threads will use - a common instance.</item> - </taglist> + SMP support is <c>NoSchedulers+1</c> instances. Each scheduler will use + a lock-free instance of its own and other threads will use + a common instance.</p> <p>It was previously (before ERTS version 5.9) possible to configure a smaller amount of thread specific instances than schedulers. This is, however, not possible any more.</p> @@ -480,6 +556,11 @@ placed in separate memory segments. When this limit has been reached, new carriers will be placed in memory retrieved from <c>sys_alloc</c>.</item> + <tag><marker id="Musac"><c><![CDATA[+Musac <bool>]]></c></marker></tag> + <item> + Allow <c>sys_alloc</c> carriers. By default <c>true</c>. If + set to <c>false</c>, <c>sys_alloc</c> carriers will never be + created by allocators using the <c>alloc_util</c> framework.</item> </taglist> <p>Instrumentation flags:</p> <taglist> @@ -535,6 +616,16 @@ </item> </taglist> </item> + <tag><marker id="Mlpm"><c>+Mlpm all|no</c></marker></tag> + <item>Lock physical memory. The default value is <c>no</c>, i.e., + no physical memory will be locked. If set to <c>all</c>, all + memory mappings made by the runtime system, will be locked into + physical memory. If set to <c>all</c>, the runtime system will fail + to start if this feature is not supported, the user has not got enough + privileges, or the user is not allowed to lock enough physical memory. + The runtime system will also fail with an out of memory condition + if the user limit on the amount of locked memory is reached. + </item> </taglist> <p>Only some default values have been presented here. diff --git a/erts/doc/src/escript.xml b/erts/doc/src/escript.xml index 9e2a87dde6..9159d68f60 100644 --- a/erts/doc/src/escript.xml +++ b/erts/doc/src/escript.xml @@ -1,10 +1,10 @@ -<?xml version="1.0" encoding="latin1" ?> +<?xml version="1.0" encoding="utf-8" ?> <!DOCTYPE comref SYSTEM "comref.dtd"> <comref> <header> <copyright> - <year>2007</year><year>2013</year> + <year>2007</year><year>2014</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -44,6 +44,7 @@ <p><c>escript</c> runs a script written in Erlang.</p> <p>Here follows an example.</p> <pre> +$ <input>chmod u+x factorial</input> $ <input>cat factorial</input> #!/usr/bin/env escript %% -*- erlang -*- @@ -66,12 +67,13 @@ usage() -> fac(0) -> 1; fac(N) -> N * fac(N-1). -$ <input>factorial 5</input> +$ <input>./factorial 5</input> factorial 5 = 120 -$ <input>factorial</input> +$ <input>./factorial</input> usage: factorial integer -$ <input>factorial five</input> -usage: factorial integer </pre> +$ <input>./factorial five</input> +usage: factorial integer + </pre> <p>The header of the Erlang script in the example differs from a normal Erlang module. The first line is intended to be the interpreter line, which invokes <c>escript</c>. However if you @@ -90,6 +92,18 @@ $ <input>escript factorial 5</input> </pre> marker="stdlib:epp#encoding">encoding</seealso> it can be located on the second line.</p> + <note><p> + The encoding specified by the above mentioned comment + applies to the script itself. The encoding of the + I/O-server, however, has to be set explicitly like this: +<code>io:setopts([{encoding, unicode}])</code></p> + <p>The default encoding of the I/O-server for <c>standard_io</c> + is <c>latin1</c> + since the script runs in a non-interactive terminal + (see <seealso marker="stdlib:unicode_usage#unicode_options_summary"> + Using Unicode in Erlang</seealso>). + </p></note> + <p>On the third line (or second line depending on the presence of the Emacs directive), it is possible to give arguments to the emulator, such as </p> @@ -139,8 +153,9 @@ halt(1).</pre> -include_lib("kernel/include/file.hrl").</pre> <p>to include the record definitions for the records used by the <c>file:read_link_info/1</c> function. You can also select - encoding here, but if there is a valid encoding comment on - the second line it takes precedence.</p> + encoding by including a encoding comment here, but if there + is a valid encoding comment on the second line it takes + precedence.</p> <p>The script will be checked for syntactic and semantic correctness before being run. If there are warnings (such as @@ -161,7 +176,7 @@ halt(1).</pre> If much of the execution takes place in interpreted code it may be worthwhile to compile it, even though the compilation itself will take a little while. It is also possible to supply - <c>native</c> instead of compile, this will compile the script + <c>native</c> instead of <c>compile</c>, this will compile the script using the native flag, again depending on the characteristics of the escript this could or could not be worth while.</p> @@ -221,8 +236,13 @@ factorial 5 = 120 <v>EmuArgs = string() | 'undefined'</v> <v>Body = {source, SourceCode} | {beam, BeamCode} - | {archive, ZipArchive}</v> - <v>SourceCode = BeamCode = ZipArchive = binary()</v> + | {archive, ZipArchive} + | {archive, ZipFiles, ZipOptions}</v> + <v>SourceCode = BeamCode = file:filename() | binary()</v> + <v>ZipArchive = <seealso marker="stdlib:zip#type-filename">zip:filename()</seealso> | binary()</v> + <v>ZipFiles = [ZipFile]</v> + <v>ZipFile = file:filename() | {file:filename(), binary()} | {file:filename(), binary(), file:file_info()}</v> + <v>ZipOptions = [<seealso marker="stdlib:zip#type-create_option">zip:create_option()</seealso>]</v> </type> <desc> <p>The <marker id="create_2"></marker> <c>create/2</c> @@ -237,7 +257,7 @@ factorial 5 = 120 can either be returned as a binary or written to file.</p> <p>As an example of how the function can be used, we create an - interpreted escript which uses emu_args to set some emulator + interpreted escript which uses <c>emu_args</c> to set some emulator flag. In this case it happens to disable the smp_support. We do also extract the different sections from the newly created script:</p> diff --git a/erts/doc/src/fascicules.xml b/erts/doc/src/fascicules.xml index cae197a516..1c371bd9c8 100644 --- a/erts/doc/src/fascicules.xml +++ b/erts/doc/src/fascicules.xml @@ -1,4 +1,4 @@ -<?xml version="1.0" encoding="latin1" ?> +<?xml version="1.0" encoding="utf-8" ?> <!DOCTYPE fascicules SYSTEM "fascicules.dtd"> <fascicules> diff --git a/erts/doc/src/inet_cfg.xml b/erts/doc/src/inet_cfg.xml index 2a033c037c..d40bc5f9ee 100644 --- a/erts/doc/src/inet_cfg.xml +++ b/erts/doc/src/inet_cfg.xml @@ -1,10 +1,10 @@ -<?xml version="1.0" encoding="latin1" ?> +<?xml version="1.0" encoding="utf-8" ?> <!DOCTYPE chapter SYSTEM "chapter.dtd"> <chapter> <header> <copyright> - <year>2004</year><year>2010</year> + <year>2004</year><year>2013</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> diff --git a/erts/doc/src/init.xml b/erts/doc/src/init.xml index d5c43f6e57..09b5493341 100644 --- a/erts/doc/src/init.xml +++ b/erts/doc/src/init.xml @@ -1,10 +1,10 @@ -<?xml version="1.0" encoding="latin1" ?> +<?xml version="1.0" encoding="utf-8" ?> <!DOCTYPE erlref SYSTEM "erlref.dtd"> <erlref> <header> <copyright> - <year>1996</year><year>2011</year> + <year>1996</year><year>2013</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> diff --git a/erts/doc/src/match_spec.xml b/erts/doc/src/match_spec.xml index bdcf9c3816..334b47d34c 100644 --- a/erts/doc/src/match_spec.xml +++ b/erts/doc/src/match_spec.xml @@ -1,10 +1,10 @@ -<?xml version="1.0" encoding="latin1" ?> +<?xml version="1.0" encoding="utf-8" ?> <!DOCTYPE chapter SYSTEM "chapter.dtd"> <chapter> <header> <copyright> - <year>1999</year><year>2012</year> + <year>1999</year><year>2013</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> diff --git a/erts/doc/src/notes.xml b/erts/doc/src/notes.xml index f94d71ee3d..24bcc76e4b 100644 --- a/erts/doc/src/notes.xml +++ b/erts/doc/src/notes.xml @@ -1,4 +1,4 @@ -<?xml version="1.0" encoding="latin1" ?> +<?xml version="1.0" encoding="utf-8" ?> <!DOCTYPE chapter SYSTEM "chapter.dtd"> <chapter> @@ -30,6 +30,2186 @@ </header> <p>This document describes the changes made to the ERTS application.</p> +<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> + <list> + <item> + <p> + Fixed a bug that could cause a crash dump to become + almost empty.</p> + <p> + Own Id: OTP-13150</p> + </item> + </list> + </section> + +</section> + +<section><title>Erts 6.4.1.4</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> + The 'raw' socket option could not be used multiple times + in one call to any e.g gen_tcp function because only one + of the occurrences were used. This bug has been fixed, + and also a small bug concerning propagating error codes + from within inet:setopts/2.</p> + <p> + Own Id: OTP-11482 Aux Id: seq12872 </p> + </item> + </list> + </section> + +</section> + +<section><title>Erts 6.4.1.3</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> + When tracing with <c>process_dump</c> option, the VM + could abort if there was an ongoing binary match + somewhere in the call stack of the traced process./</p> + <p> + Own Id: OTP-12968</p> + </item> + </list> + </section> + +</section> + +<section><title>Erts 6.4.1.2</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> + A process could end up in an inconsistent half exited + state in the runtime system without SMP support. This + could occur if the processes was traced by a port that it + also was linked to, and the port terminated abnormally + while handling a trace message for the process.</p> + <p> + This bug has always existed in the runtime system without + SMP support, but never in the runtime system with SMP + support.</p> + <p> + Own Id: OTP-12889 Aux Id: seq12885 </p> + </item> + </list> + </section> + +</section> + +<section><title>Erts 6.4.1.1</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p>Fix garbage collection of literals in code purge</p> + <p>During code purging and check_process_code, the + checking of the binary reference embedded in the match + binary state was omitted for the tracing tests. This + would cause the binary match state to reference + deallocated memory.</p> + <p> + Own Id: OTP-12821</p> + </item> + <item> + <p> + Fix a rare hanging of the VM seen to happen just after + emulator start. Bug exists since R14.</p> + <p> + Own Id: OTP-12859 Aux Id: seq12882 </p> + </item> + </list> + </section> + +</section> + +<section><title>Erts 6.4.1</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> + The VTS mode in Common Test has been modified to use a + private version of the Webtool application (ct_webtool).</p> + <p> + Own Id: OTP-12704 Aux Id: OTP-10922 </p> + </item> + </list> + </section> + +</section> + +<section><title>Erts 6.4</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> + Fix missing quotation in the <c>LM_FIND_EMU_CC</c> + <c>autoconf</c> macro which could cause build failures.</p> + <p> + Own Id: OTP-12388</p> + </item> + <item> + <p> + Fix erroneous printout of monitors in crashdump file.</p> + <p> + Own Id: OTP-12537</p> + </item> + <item> + <p> + The runtime system without SMP support could crash in the + BIF <c>port_control/3</c> if the port that was being + accessed died during the call to the BIF.</p> + <p> + Own Id: OTP-12544 Aux Id: Seq12777 </p> + </item> + <item> + <p> + Avoid corrupt oversized integer to be created from binary + matching. Instead throw system_limit exception which is + the correct behavior. A peculiar symptom of this bug was + that bitwise operations (band, bor, bxor) on such + oversized integers could return the empty list []. + Credit: Mikael Pettersson, Nico Kruber</p> + <p> + Own Id: OTP-12556</p> + </item> + <item> + <p> + A race condition when calling <c>port_info/1</c> could + cause a memory fault has been fixed.</p> + <p> + Own Id: OTP-12587</p> + </item> + <item> + <p> + Fix comparison of exact terms. An overflow that could + cause faulty comparisons has been fixed. Comparison of + exact terms is exclusively used within Maps.</p> + <p> + Own Id: OTP-12623</p> + </item> + <item> + <p> + Fix bug in <c>list_to_integer/1</c> for very long lists + that could cause VM crash.</p> + <p> + Own Id: OTP-12624</p> + </item> + </list> + </section> + + + <section><title>Improvements and New Features</title> + <list> + <item> + <p> + Introduced a runtime system internal 64-bit API for + atomic memory operations.</p> + <p> + Own Id: OTP-12351</p> + </item> + <item> + <p> + Add command line argument option for the initial size of + process dictionaries.</p> + <p> + Use '+hpds <size>' to set initial process + dictionary size for spawned processes.</p> + <p> + Own Id: OTP-12535 Aux Id: seq12809 </p> + </item> + <item> + <p> + Fix documentation on $char for Unicode</p> + <p> + Own Id: OTP-12545</p> + </item> + </list> + </section> + +</section> + +<section><title>Erts 6.3.1</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> + Fix getifaddrs realloc pointer error</p> + <p> + When a buffer was exhausted and subsequently reallocated, + we could get an unsafe pointer pointing to faulty memory.</p> + <p> + For this to occur we would need to have a large number of + interfaces and a reallocation of memory to a lower + addresses.</p> + <p> + The symptom would be garbage returned from + erlang:port_control(Port, 25, []) + (prim_inet:getifaddrs(Port) resulting in a badarg) or a + segmentation fault.</p> + <p> + Own Id: OTP-12445</p> + </item> + <item> + <p> + Don't close all file descriptors twice in child_setup</p> + <p> + The commit c2b4eab25c907f453a394d382c04cd04e6c06b49 + introduced an error in which child_setup erroneously + tried to close all file descriptors twice.</p> + <p> + Use closefrom() if available when closing all file + descriptors.</p> + <p> + The function closefrom() was only used in the vfork() + case before but is now also used in the fork() case if + available.</p> + <p> + Own Id: OTP-12446</p> + </item> + <item> + <p> + During a crashdump all file descriptors are closed to + ensure the closing of the epmd port and to reserve a file + descriptor for the crashdump file.</p> + <p> + If a driver (third party library) cannot handle closing + of sockets this could result in a segmentation fault in + which case a crashdump would not be produced. This is now + fixed by only closing inets sockets via an emergency + close callback to the driver and thus closing the epmd + socket.</p> + <p> + Own Id: OTP-12447</p> + </item> + </list> + </section> + +</section> + +<section><title>Erts 6.3</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> + Fix HiPE debug lock checking on OS X 64bit</p> + <p> + Position-independent code is mandatory on OS X. We use + r11 as an intermediate register to fill + BIF_P->hipe.bif_callee. This fixes the following error + when doing `make debug FLAVOR=smp`:</p> + <p> + clang -cc1as: fatal error: error in backend: 32-bit + absolute addressing is not supported in 64-bit mode</p> + <p> + Own Id: OTP-12188</p> + </item> + <item> + <p> + Fix race bug that could cause VM crash in + <c>erlang:port_get_data/1</c> if the port was closed by a + concurrent process. Also fix fatal bug if + <c>port_set_data/2</c> is called with a non-immediate + data term. Both bugs exist since R16B01.</p> + <p> + Own Id: OTP-12208</p> + </item> + <item> + <p> + Correct make variable SSL_DED_LD_RUNTIME_LIBRARY_PATH + when erl_xcomp_sysroot ends with a slash.</p> + <p> + Own Id: OTP-12216 Aux Id: seq12700 </p> + </item> + <item> + <p> + Fix two cases of unreachable code caused by false use of + assigment operators.</p> + <p> + Own Id: OTP-12222</p> + </item> + <item> + <p> + Fix bug when hipe compiled code makes tail call to a BIF + that disables GC while trapping (sush as binary_to_list, + list_to_binary, binary_to_term, term_to_binary).</p> + <p> + Own Id: OTP-12231</p> + </item> + <item> + <p> + Fix bug when a migrated empty memory carrier is reused + just before it should be destroyed by the thread that + created it.</p> + <p> + Own Id: OTP-12249</p> + </item> + <item> + <p> + Prevents compile-time errors in NIFs, when the compiler + is instructed to treat missing field initializers as + errors, by adding an initializer for the new options + field which was added to ErlNifEntry for 17.3.</p> + <p> + Own Id: OTP-12266</p> + </item> + <item> + <p> + Fixed CPU topology detection on FreeBSD systems where + Erlang/OTP is compiled by new C compilers (including, but + possibly not limited to, gcc 4.9 and clang).</p> + <p> + Own Id: OTP-12267</p> + </item> + <item> + <p> + Use C99 function isfinite() instead of finite() when + available on non GCC compilers.</p> + <p> + Own Id: OTP-12268</p> + </item> + <item> + <p> + Fix bug on windows where an incorrect number of links + could be returned when doing file:read_file_info on a + directory.</p> + <p> + Own Id: OTP-12269</p> + </item> + <item> + <p> + Fix rare bug when purging module on VM started with + +Meamin.</p> + <p> + Own Id: OTP-12273</p> + </item> + <item> + <p> + Repair run_erl terminal window size adjustment sent from + to_erl. This was broken in OTP 17.0 which could lead to + strange cursor behaviour in the to_erl shell.</p> + <p> + Own Id: OTP-12275 Aux Id: seq12739 </p> + </item> + <item> + <p> + Fixed bug on windows causing gen_tcp/udp to return an + error when given an fd to work with.</p> + <p> + Own Id: OTP-12289</p> + </item> + <item> + <p> + Fix various internal erts issues where negating a signed + integer in C would trigger undefined behavior. This fixes + issues when dividing with bignums and list_to_integer.</p> + <p> + Own Id: OTP-12290</p> + </item> + <item> + <p> + When flushing output to stdout on windows, the emulator + could sometimes hang indefinitely waiting for the flush + to complete. This has been fixed.</p> + <p> + Own Id: OTP-12291</p> + </item> + <item> + <p> + Fix so that non-smp emulators with dirty scheduler + support shows the correct number of dirty schedulers when + calling erlang:system_info(system_version).</p> + <p> + Own Id: OTP-12295</p> + </item> + <item> + <p> + Add <c>nif_version</c> to <c>erlang:system_info/1</c> in + order to get the NIF API version of the runtime system in + a way similar to <c>driver_version</c>.</p> + <p> + Own Id: OTP-12298</p> + </item> + <item> + <p> + Fix bug that could cause the return value from dirty NIF + with zero arity to be treated as garbage, leading to VM + crash.</p> + <p> + Own Id: OTP-12300</p> + </item> + <item> + <p> + Improve allocation carrier migration search logic. This + will reduce the risk of failed migrations that could lead + to excess memory consumption. It will also improve smp + performance due to reduced memory contention on the + migration pool.</p> + <p> + Own Id: OTP-12323</p> + </item> + </list> + </section> + + + <section><title>Improvements and New Features</title> + <list> + <item> + <p>Introduced support for eager check I/O.</p> + <p>By default eager check I/O will be disabled, but this + will most likely be changed in OTP 18. When eager check + I/O is enabled, schedulers will more frequently check for + I/O work. Outstanding I/O operations will however not be + prioritized to the same extent as when eager check I/O is + disabled.</p> + <p>Eager check I/O can be enabled using the <c>erl</c> + command line argument: <seealso + marker="erl#+secio"><c>+secio true</c></seealso></p> + <p>Characteristics impact when enabled:</p> <list> + <item>Lower latency and smoother management of externally + triggered I/O operations.</item> <item>A slightly reduced + priority of externally triggered I/O operations.</item> + </list> + <p> + Own Id: OTP-12117</p> + </item> + <item> + <p> + Fix erts .app-file</p> + <p> + Own Id: OTP-12189</p> + </item> + <item> + <p> + Add configure option --with-ssl-incl=PATH to support + OpenSSL installations with headers and libraries at + different places.</p> + <p> + Own Id: OTP-12215 Aux Id: seq12700 </p> + </item> + <item> + <p> + Optimization of atomic memory operations with release + barrier semantics on 32-bit PowerPC when using the + implementation included in OTP.</p> + <p> + Own Id: OTP-12250</p> + </item> + <item> + <p> + Minor adjustment of scheduler activation code making sure + that an activation of a scheduler is not prevented by its + run-queue being non-empty. (Thanks to Songlu Cai)</p> + <p> + Own Id: OTP-12287</p> + </item> + <item> + <p> + Improved support for atomic memory operations provided by + the <url + href="https://github.com/ivmai/libatomic_ops/"><c>libatomic_ops</c></url> + library. Most importantly support for use of native + double word atomics when implemented by + <c>libatomic_ops</c> (for example, implemented for ARM).</p> + <p> + The <seealso + marker="doc/installation_guide:INSTALL#Advanced-configuration-and-build-of-ErlangOTP_Configuring_Atomic-Memory-Operations-and-the-VM"><c>$ERL_TOP/HOWTO/INSTALL.md</c></seealso> + document now also more clearly describes when you want to + build together with a <c>libatomic_ops</c> installation.</p> + <p> + Own Id: OTP-12302</p> + </item> + <item> + <p> + Add configure option --with-ssl-rpath to control which + runtime library path to use for dynamic linkage toward + OpenSSL.</p> + <p> + Own Id: OTP-12316 Aux Id: seq12753 </p> + </item> + <item> + <p> + Added systemd notify support to epmd</p> + <p> + Own Id: OTP-12321</p> + </item> + </list> + </section> + +</section> + +<section><title>Erts 6.2.1</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> + Fix bug when an migrated empty memory carrier is reused + just before it should be destroyed by the thread that + created it.</p> + <p> + Own Id: OTP-12249</p> + </item> + <item> + <p> + Repair run_erl terminal window size adjustment sent from + to_erl. This was broken in OTP 17.0 which could lead to + strange cursor behaviour in the to_erl shell.</p> + <p> + Own Id: OTP-12275 Aux Id: seq12739 </p> + </item> + </list> + </section> + +</section> + +<section><title>Erts 6.2</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> + General documentation updates.</p> + <p> + Own Id: OTP-12052</p> + </item> + <item> + <p>A bug in the VM code implementing sending of signals + to ports could cause the receiving port queue to remain + in a busy state forever. When this state had been + reached, processes sending command signals to the port + either got suspended forever, or, if the <c>nosuspend</c> + feature was used, always failed to send to the port. This + bug was introduced in ERTS version 5.10.</p> + <p>In order for this bug to be triggered on a port, one + had to at least once utilize the <c>nosuspend</c> + functionality when passing a signal to the port. This by + either calling</p> <list> <item> <seealso + marker="erlang#port_command/3"><c>port_command(Port, + Data, [nosuspend | Options])</c></seealso>, </item> + <item> <seealso + marker="erlang#send/3"><c>erlang:send(Port, {PortOwner, + {command, Data}}, [nosuspend | Options])</c></seealso>, + </item> <item> <seealso + marker="erlang#send_nosuspend/2"><c>erlang:send_nosuspend(Port, + {PortOwner, {command, Data}})</c></seealso>, or </item> + <item> <seealso + marker="erlang#send_nosuspend/3"><c>erlang:send_nosuspend(Port, + {PortOwner, {command, Data}}, Options)</c></seealso>. + </item> </list> + <p>Thanks Vasily Demidenok for reporting the issue, and + Sergey Kudryashov for providing a testcase.</p> + <p> + Own Id: OTP-12082 Aux Id: OTP-10336 </p> + </item> + <item> + <p> + Fix size overflow bug at memory allocation. A memory + allocation call, with an insane size close to the entire + address space, could return successfully as if it had + allocated just a few bytes. (Thanks to Don A. Bailey for + reporting)</p> + <p> + Own Id: OTP-12091</p> + </item> + <item> + <p> + Fix various issues where negating a signed integer would + trigger undefined behaviour. This fixes issues in the + enif_make_int64 interface and some edge cases inside the + erlang runtime system.</p> + <p> + Own Id: OTP-12097</p> + </item> + <item> + <p> + The documentation erroneously listed the <seealso + marker="erl#+swct"><c>+swct</c></seealso> command line + argument under <c>+sws</c>.</p> + <p> + Own Id: OTP-12102 Aux Id: OTP-10994 </p> + </item> + <item> + <p> + Profiling messages could be delivered out of order when + profiling on <c>runnable_procs</c> and/or + <c>runnable_ports</c> using <seealso + marker="erlang#system_profile/2"><c>erlang:system_profile/2</c></seealso>. + This bug was introduced in ERTS version 5.10.</p> + <p> + Own Id: OTP-12105 Aux Id: OTP-10336 </p> + </item> + <item> + <p> + Various logging fixes, including: Add run queue index to + the process dump in crash dumps.<br/> Add thread index to + enomem slogan when crashing.<br/> Remove error logger + message for sending messages to old instances of the same + node.</p> + <p> + Own Id: OTP-12115</p> + </item> + <item> + <p> + Fix compiler warnings reported by LLVM</p> + <p> + Own Id: OTP-12138</p> + </item> + <item> + <p> + Correct conversion of <c>MIN_SMALL</c> by + <c>list_to_integer/1</c> and <c>binary_to_integer/1</c>. + The bug produced an unnormalized bignum which can cause + strange behavior such as comparing different to a correct + <c>MIN_SMALL</c> integer. The value <c>MIN_SMALL</c> is + <c>-(1 bsl 27) = -134217728</c> on a 32-bit VM and <c>-(1 + bsl 59) = -576460752303423488</c> on a 64-bit VM. (Thanks + to Jesper Louis Andersen, Mikael Pettersson and Anthony + Ramine for report, patch and optimization suggestion)</p> + <p> + Own Id: OTP-12140</p> + </item> + <item> + <p> + Fix bug in <c>term_to_binary</c> that reallocates binary + with inconsistent size information. Bug has never been + confirmed to be the cause of any faulty behavior.</p> + <p> + Own Id: OTP-12141</p> + </item> + <item> + <p> + Real_path method used while prim loading archive files + was not taking into account the fact that windows + directory symlinks can be across different drives.</p> + <p> + Own Id: OTP-12155</p> + </item> + </list> + </section> + + + <section><title>Improvements and New Features</title> + <list> + <item> + <p> + Add log2 histogram to lcnt for lock wait time</p> + <p> + Own Id: OTP-12059</p> + </item> + <item> + <p> + Introduced <seealso + marker="erl_nif#enif_schedule_nif"><c>enif_schedule_nif()</c></seealso> + to the NIF API.</p> + <p> + The <c>enif_schedule_nif()</c> function allows a + long-running NIF to be broken into separate NIF + invocations without the help of a wrapper function + written in Erlang. The NIF first executes part of the + long-running task, then calls <c>enif_schedule_nif()</c> + to schedule a NIF for later execution to continue the + task. Any number of NIFs can be scheduled in this manner, + one after another. Since the emulator regains control + between invocations, this helps avoid problems caused by + native code tying up scheduler threads for too long.</p> + <p> + The <c>enif_schedule_nif()</c> function also replaces the + <c>enif_schedule_dirty_nif()</c> in the experimental + dirty NIF API. Note that the only incompatible changes + made are in the experimental dirty NIF API.</p> + <p> + See the <seealso marker="erl_nif">NIF + documentation</seealso> for more information.</p> + <p> + Thanks to Steve Vinoski.</p> + <p> + *** POTENTIAL INCOMPATIBILITY ***</p> + <p> + Own Id: OTP-12128</p> + </item> + </list> + </section> + +</section> + +<section><title>Erts 6.1.2</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> + OTP-11850 fixed filelib:wildcard/1 to work with broken + symlinks. This correction, however, introduced problems + since symlinks were no longer followed for functions like + filelib:ensure_dir/1, filelib:is_dir/1, + filelib:file_size/1, etc. This is now corrected.</p> + <p> + Own Id: OTP-12054 Aux Id: seq12660 </p> + </item> + </list> + </section> + +</section> + +<section><title>Erts 6.1.1</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> + Fixed ETHR_FORCE_INLINE which caused the build to break + on some platforms without adequate thread support + (VxWorks).</p> + <p> + Own Id: OTP-12010</p> + </item> + </list> + </section> + +</section> + +<section><title>Erts 6.1</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p>The documentation for <c>spawn_opt/5</c> now has a + note mentioning that the <c>monitor</c> option is not + supported.</p> + <p> + Own Id: OTP-11849</p> + </item> + <item> + <p> + Fix broken system monitoring of <c>large_heap</c> for + non-smp VM. No message for <c>large_heap</c> was ever + sent on non-smp VM. Bug exist since R16B.</p> + <p> + Own Id: OTP-11852</p> + </item> + <item> + <p> + The emulator without SMP support crashed when passing a + message to a process without enough heap space for the + message. This bug was introduced in <c>erts-6.0</c>.</p> + <p> + Own Id: OTP-11887 Aux Id: OTP-11388 </p> + </item> + <item> + <p> + Fix race between ETS table deletion and unfixation that + could cause VM crash. The race could happen between a + terminating process that does not own the table but has a + fixation on it and another process that deletes the table + (maybe the owner terminating) at the same time. Bug + existed since R15B02.</p> + <p> + Own Id: OTP-11892</p> + </item> + <item> + <p>The string following the <c>-eval</c> option when + invoking <c>erl</c> would not be properly translated from + UTF-8 to a list of Unicode characters (as would the + arguments for <c>-run</c>).</p> + <p>That bug would cause the build of Erlang/OTP to fail + when building in a directory whose pathname contained + non-US ASCII characters encoded in UTF-8. (Thanks to Eric + Pailleau for reporting this bug.)</p> + <p> + Own Id: OTP-11916</p> + </item> + <item> + <p> + Fix erts_debug:size/1 to handle Map sizes</p> + <p> + Own Id: OTP-11923</p> + </item> + <item> + <p> + Removed <c>erlang:bitstr_to_list/1</c> and + <c>erlang:list_to_bitstr/1</c>. They were added by + mistake, and have always raised an <c>undefined</c> + exception when called.</p> + <p> + Own Id: OTP-11942</p> + </item> + <item> + <p> + Fixed compilation using mingw-w64 on Windows.</p> + <p> + Thanks to Jani Hakala.</p> + <p> + Own Id: OTP-11945</p> + </item> + <item> + <p> + The git sha is no longer printed in the shell start + header when erlang is built from a tagged git release.</p> + <p> + Own Id: OTP-11961</p> + </item> + <item> + <p> + Fixed a bug where <c>send</c> trace events were + erroneously dropped when the send was done to a + registered process. This bug was introduced in R16B.</p> + <p> + Own Id: OTP-11968</p> + </item> + </list> + </section> + + + <section><title>Improvements and New Features</title> + <list> + <item> + <p>The following native functions now bump an appropriate + amount of reductions and yield when out of + reductions:</p> <list> + <item><c>erlang:binary_to_list/1</c></item> + <item><c>erlang:binary_to_list/3</c></item> + <item><c>erlang:bitstring_to_list/1</c></item> + <item><c>erlang:list_to_binary/1</c></item> + <item><c>erlang:iolist_to_binary/1</c></item> + <item><c>erlang:list_to_bitstring/1</c></item> + <item><c>binary:list_to_bin/1</c></item> </list> + <p>Characteristics impact:</p> <taglist> + <tag>Performance</tag> <item>The functions converting + from lists got a performance loss for very small lists, + and a performance gain for very large lists.</item> + <tag>Priority</tag> <item>Previously a process executing + one of these functions effectively got an unfair priority + boost. This priority boost depended on the input size. + The larger the input was, the larger the priority boost + got. This unfair priority boost is now lost. </item> + </taglist> + <p> + Own Id: OTP-11888</p> + </item> + <item> + <p> + The systemd features of epmd have been removed from epmd + by default. To enable them you have to build erlang with + the configure option --enable-systemd.</p> + <p> + Own Id: OTP-11921</p> + </item> + <item> + <p> + Removed Erlang wrapper code used when calling + <c>binary_to_term/1</c>, and <c>binary_to_term/2</c>. + This improves the performance of these BIFs especially + when they are called with small binaries as input.</p> + <p> + Own Id: OTP-11931</p> + </item> + <item> + <p> + Add erlang:system_info(tolerant_timeofday), an API to + check whether compensation for sudden changes of system + time is enabled or not.</p> + <p> + Own Id: OTP-11970</p> + </item> + </list> + </section> + +</section> + +<section><title>Erts 6.0.1</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> + Fix broken system monitoring of <c>large_heap</c> for + non-smp VM. No message for <c>large_heap</c> was ever + sent on non-smp VM. Bug exist since R16B.</p> + <p> + Own Id: OTP-11852</p> + </item> + <item> + <p> + Fixed type spec of <c>erlang:system_info/1</c>.</p> + <p> + Own Id: OTP-11859 Aux Id: OTP-11615 </p> + </item> + </list> + </section> + +</section> + +<section><title>Erts 6.0</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> + The option dupnames did not work as intended in re. When + looking for names with {capture, [Name, ...]}, re:run + returned a random instance of the match for that name, + instead of the leftmost matching instance, which was what + the documentation stated. This is now corrected to adhere + to the documentation. The option {capture,all_names} + along with a re:inspect/2 function is also added to + further help in using named subpatterns.</p> + <p> + Own Id: OTP-11205</p> + </item> + <item> + <p> + Allow loading of NIF library with unicode path name</p> + <p> + Own Id: OTP-11408</p> + </item> + <item> + <p> + Allow loading of driver with unicode path name</p> + <p> + Own Id: OTP-11549</p> + </item> + <item> + <p> + Fixed a bug where starting Erlang without having an open + stdin on fd 0 would sometimes deadlock the emulator when + terminating.</p> + <p> + Own Id: OTP-11558</p> + </item> + <item> + <p> + The option '-names' in epmd now works on Windows (Thanks + to Johannes Weißl)</p> + <p> + Own Id: OTP-11565</p> + </item> + <item> + <p> + Correction of the examples in escript documentation. + (Thanks to Pierre Fenoll).</p> + <p> + Own Id: OTP-11577</p> + </item> + <item> + <p> + Fix bs_get_integer instruction</p> + <p> + The instruction bs_get_integer could unnecessarily + trigger a garbage collection in failure cases which is + unwanted or outright dangerous.</p> + <p> + Ex:</p> + <p> + <<X:Sz,_/bits>> = <<"some + binary">></p> + <p> + Previously, if Sz induced X to a bignum it would reserved + memory size this on the heap via a garbage collection + before checking if the size could actually match.</p> + <p> + It will now check the binary size before triggering a + collection.</p> + <p> + Own Id: OTP-11581</p> + </item> + <item> + <p> + Remove heap space overestimation in <c>binary_to_term</c> + (and remote message reception) for integers in the + intervals [-2147483648,-1] and [256,2147483647] on 64-bit + emulators.</p> + <p> + Own Id: OTP-11585</p> + </item> + <item> + <p> + Add support for detecting the separate tinfo library from + ncurses (Thanks to Dirkjan Ochtman)</p> + <p> + Own Id: OTP-11590</p> + </item> + <item> + <p> + Deprecation warning for system_flag(cpu_topology) has + been extended for removal in OTP 18 (Thanks to Steve + Vinoski for the update)</p> + <p> + Own Id: OTP-11602</p> + </item> + <item> + <p> + Documentation improvement regarding some awkward wording + around the +spp flag. (Thanks to Brian L. Troutwine )</p> + <p> + Own Id: OTP-11607</p> + </item> + <item> + <p> + Fixed bug where sendfile would return the wrong error + code for a remotely closed socket if the socket was in + passive mode. (Thanks to Vincent Siliakus for reporting + the bug.)</p> + <p> + Own Id: OTP-11614</p> + </item> + <item> + <p> + Increase garbage collection tenure rate</p> + <p>The garbage collector tries to maintain the previous + heap block size during a minor gc, i.e. 'need' is not + utilized in determining the size of the new heap, instead + it relies on tenure and garbage to be sufficiently + large.</p> + <p>In instances during intense growing with exclusively + live data on the heap coupled with delayed tenure, + fullsweeps would be triggered directly after a minor gc + to make room for 'need' since the new heap would be + full.</p> + <p>To remedy this, the tenure of terms on the minor heap + will always happen (if it is below the high watermark) + instead of every other minor gc.</p> + <p>Characteristics Impact: Reduced CPU-time spent in + garbage collection but may infer delays in collecting + garbage from the heap. Tweak 'fullsweep_after' options to + increase gc pressure if needed.</p> + <p> + Own Id: OTP-11617</p> + </item> + <item> + <p> + Fix bug when comparing integers with floats larger than + 2^992. The bug could potentially cause memory corruption + on 32-bit emulators.</p> + <p> + Own Id: OTP-11618</p> + </item> + <item> + <p> + Cross-compilation fixes for TileraMDE-3.0.1.125620</p> + <p> + Own Id: OTP-11635</p> + </item> + <item> + <p> + sendfile no longer uses async threads by default</p> + <p> + This has been done because a slow client attack is + possible if the async thread pool is used. The scenario + is:</p> + <p> + Client does a request for a file and then slowly receives + the file one byte at a time. This will eventually fill + the async thread pool with blocking sendfile operations + and thus starving the vm of all file operations.</p> + <p> + If you still want to use the async threads pool for + sendfile an option to enable it has been introduced.</p> + <p> + Thanks to Christopher Faulet for identifying this + vulnerability.</p> + <p> + *** POTENTIAL INCOMPATIBILITY ***</p> + <p> + Own Id: OTP-11639</p> + </item> + <item> + <p> + Do proper rollback of calls to + <c>enif_open_resource_type</c> when load/upgrade + callbacks of NIF library return failure.</p> + <p> + Own Id: OTP-11722</p> + </item> + <item> + <p> + Changed the default configuration when configuring with + <c>$ERL_TOP/configure</c> to be the same as when + configuring with <c>$ERL_TOP/otp_build configure</c>.</p> + <p> + Previously floating point exceptions got enabled by + default on Linux when HiPE was enabled when configuring + with <c>$ERL_TOP/configure</c>, but not when configuring + with <c>$ERL_TOP/otp_build configure</c>. The default is + now in both cases not to use floating point exceptions + since there still exist unresolved issues with floating + point exceptions on Linux.</p> + <p> + For more information see <seealso + marker="doc/installation_guide:INSTALL"><c>$ERL_TOP/HOWTO/INSTALL.md</c></seealso>.</p> + <p> + *** POTENTIAL INCOMPATIBILITY ***</p> + <p> + Own Id: OTP-11723</p> + </item> + <item> + <p> + A comment in erl_db_tree.c no longer differ from the + code. (Thanks to Cobus Carstens)</p> + <p> + Own Id: OTP-11793</p> + </item> + <item> + <p> + Fix epmd debug functionality for VxWorks (Thanks to Jay + True)</p> + <p> + Own Id: OTP-11808</p> + </item> + <item> + <p> + Use closefrom/2 when available in child_setup (Thanks to + Rick Reed and Anthony Ramine)</p> + <p> + Own Id: OTP-11809</p> + </item> + <item> + <p> + Fix dtrace/systemtap bug where the probe arguments would + be concatenated due to faulty length calculation. </p> + <p> + Thanks to Michal Ptaszek and Scott Lystig Fritchie</p> + <p> + Own Id: OTP-11816</p> + </item> + <item> + <p> + It is now better documented that the <c>+fn*</c> flags to + <c>erl</c> also affect how command line parameters and + environment variables are read. (Thanks to Vlad + Dumitrescu)</p> + <p> + Own Id: OTP-11818</p> + </item> + </list> + </section> + + + <section><title>Improvements and New Features</title> + <list> + <item> + <p> + Options to set match_limit and match_limit_recursion are + added to re:run. The option report_errors is also added + to get more information when re:run fails due to limits + or compilation errors.</p> + <p> + Own Id: OTP-10285</p> + </item> + <item> + <p> Dialyzer's <c>unmatched_return</c> warnings have been + corrected. </p> + <p> + Own Id: OTP-10908</p> + </item> + <item> + <p> + A common case is to wrap an argument to + <c>list_to_binary/1</c> in a list to ensure conversion + can happen even though the argument may already be a + binary. Take special care of this case and do not copy + binary.</p> + <p> + Impact: May cause incompatibility since a single binary + is no longer copied. Use <c>binary:copy/1,2</c> instead.</p> + <p> + *** POTENTIAL INCOMPATIBILITY ***</p> + <p> + Own Id: OTP-11082</p> + </item> + <item> + <p> + Make erlang:open_port/2 spawn and spawn_executable handle + unicode.</p> + <p> + Own Id: OTP-11105</p> + </item> + <item> + <p> + Handle unicode (widestring) in erl, erlc, heart, etc on + windows.</p> + <p> + Own Id: OTP-11135</p> + </item> + <item> + <p> + The version of the PCRE library Used by Erlang's re + module is raised to 8.33 from 7.6. This means, among + other things, better Unicode and Unicode Character + Properties support. New options connected to PCRE 8.33 + are also added to the re module (ucd, notempty_atstart, + no_start_optimize). PCRE has extended the regular + expression syntax between 7.6 and 8.33, why this imposes + a potential incompatibility. Only very complicated + regular expressions may be affected, but if you know you + are using obscure features, please test run your regular + expressions and verify that their behavior has not + changed.</p> + <p> + *** POTENTIAL INCOMPATIBILITY ***</p> + <p> + Own Id: OTP-11204</p> + </item> + <item> + <p>Filenames containing UTF-8 encoded characters can now + be handled by erlc.</p> + <p>If you have set the <c>ERLC_EMULATOR</c> environment + variable, note that <c>erlc</c> in OTP 17 will only work + with <c>erl</c> in OTP 17 since the protocol between the + <c>erlc</c> program and the <c>erl_compile</c> module has + changed.</p> + <p> + Own Id: OTP-11248</p> + </item> + <item> + <p> + By giving --enable-static-{nifs,drivers} to configure it + is now possible to statically linking of nifs and drivers + to the main Erlang VM binary. At the moment only the asn1 + and crypto nifs of the Erlang/OTP nifs and drivers have + been prepared to be statically linked. For more details + see the Installation Guide in the System documentation.</p> + <p> + Own Id: OTP-11258</p> + </item> + <item> + <p> + Erlang/OTP has been ported to the realtime operating + system OSE. The port supports both smp and non-smp + emulator. For details around the port and how to started + see the User's Guide in the <seealso + marker="ose:ose_intro">ose</seealso> application. </p> + <p> + Note that not all parts of Erlang/OTP has been ported. </p> + <p> + Notable things that work are: non-smp and smp emulators, + OSE signal interaction, crypto, asn1, run_erl/to_erl, + tcp, epmd, distribution and most if not all non-os + specific functionality of Erlang.</p> + <p> + Notable things that does not work are: udp/sctp, os_mon, + erl_interface, binding of schedulers.</p> + <p> + Own Id: OTP-11334</p> + </item> + <item> + <p> + Add the {active,N} socket option for TCP, UDP, and SCTP, + where N is an integer in the range -32768..32767, to + allow a caller to specify the number of data messages to + be delivered to the controlling process. Once the + socket's delivered message count either reaches 0 or is + explicitly set to 0 with inet:setopts/2 or by including + {active,0} as an option when the socket is created, the + socket transitions to passive ({active, false}) mode and + the socket's controlling process receives a message to + inform it of the transition. TCP sockets receive + {tcp_passive,Socket}, UDP sockets receive + {udp_passive,Socket} and SCTP sockets receive + {sctp_passive,Socket}. </p> + <p> + The socket's delivered message counter defaults to 0, but + it can be set using {active,N} via any gen_tcp, gen_udp, + or gen_sctp function that takes socket options as + arguments, or via inet:setopts/2. New N values are added + to the socket's current counter value, and negative + numbers can be used to reduce the counter value. + Specifying a number that would cause the socket's counter + value to go above 32767 causes an einval error. If a + negative number is specified such that the counter value + would become negative, the socket's counter value is set + to 0 and the socket transitions to passive mode. If the + counter value is already 0 and inet:setopts(Socket, + [{active,0}]) is specified, the counter value remains at + 0 but the appropriate passive mode transition message is + generated for the socket.</p> + <p> + Thanks to Steve Vinoski</p> + <p> + Own Id: OTP-11368</p> + </item> + <item> + <p> + A new optional scheduler utilization balancing mechanism + has been introduced. For more information see the + <seealso marker="erl#+sub"><c>+sub</c></seealso> command + line argument.</p> + <p> + Characteristics impact: None, when not enabled. When + enabled, changed timing in the system, normally a small + overhead due to measuring of utilization and calculating + balancing information. On some systems, such as old + Windows systems, the overhead can be quite substantial. + This time measurement overhead highly depend on the + underlying primitives provided by the OS.</p> + <p> + Own Id: OTP-11385</p> + </item> + <item> + <p> + A call to either the <c>garbage_collect/1</c> BIF or the + <c>check_process_code/2</c> BIF may trigger garbage + collection of another processes than the process calling + the BIF. The previous implementations performed these + kinds of garbage collections without considering the + internal state of the process being garbage collected. In + order to be able to more easily and more efficiently + implement yielding native code, these types of garbage + collections have been rewritten. A garbage collection + like this is now triggered by an asynchronous request + signal, the actual garbage collection is performed by the + process being garbage collected itself, and finalized by + a reply signal to the process issuing the request. Using + this approach processes can disable garbage collection + and yield without having to set up the heap in a state + that can be garbage collected.</p> + <p> + The <seealso + marker="erts:erlang#garbage_collect/2"><c>garbage_collect/2</c></seealso>, + and <seealso + marker="erts:erlang#check_process_code/3"><c>check_process_code/3</c></seealso> + BIFs have been introduced. Both taking an option list as + last argument. Using these, one can issue asynchronous + requests.</p> + <p> + <c>code:purge/1</c> and <c>code:soft_purge/1</c> have + been rewritten to utilize asynchronous + <c>check_process_code</c> requests in order to + parallelize work.</p> + <p> + Characteristics impact: A call to the + <c>garbage_collect/1</c> BIF or the + <c>check_process_code/2</c> BIF will normally take longer + time to complete while the system as a whole wont be as + much negatively effected by the operation as before. A + call to <c>code:purge/1</c> and <c>code:soft_purge/1</c> + may complete faster or slower depending on the state of + the system while the system as a whole wont be as much + negatively effected by the operation as before.</p> + <p> + Own Id: OTP-11388 Aux Id: OTP-11535, OTP-11648 </p> + </item> + <item> + <p> + Cleanup 'Buckets' and 'Time left' fields in crashdump to + ease parsing.</p> + <p> + Own Id: OTP-11419</p> + </item> + <item> + <p> + Add sync option to file:open/2.</p> + <p> + The sync option adds the POSIX O_SYNC flag to the open + system call on platforms that support the flag or its + equivalent, e.g., FILE_FLAG_WRITE_THROUGH on Windows. For + platforms that don't support it, file:open/2 returns + {error, enotsup} if the sync option is passed in. Thank + to Steve Vinoski and Joseph Blomstedt</p> + <p> + Own Id: OTP-11498</p> + </item> + <item> + <p> + erlang:binary_to_term will now cost an appropriate amount + of reductions and will interrupt (yield) for reschedule + if the term is big. This avoids too long schedules when + binary_to_term is used. (Thanks to Svante Karlsson for + the original patch)</p> + <p> + Impact: Programs running binary_to_term on large binaries + will run more smoothly, but rescheduling will impact the + single process performance of the BIF. Single threaded + benchmarks might show degraded performance of the BIF, + while general system behaviour will be improved.</p> + <p> + Own Id: OTP-11535 Aux Id: OTP-11388 </p> + </item> + <item> + <p> + Added high resolution icon for windows. (Thanks to Daniel + Goertz for the inspiration.)</p> + <p> + Own Id: OTP-11560</p> + </item> + <item> + <p> + Migration of memory carriers has been enabled by default + on all ERTS internal memory allocators based on the + <seealso + marker="erts_alloc#alloc_util"><c>alloc_util</c></seealso> + framework except for <c>temp_alloc</c>. That is, <seealso + marker="erts_alloc#M_acul"><c>+M<S>acul + de</c></seealso> is default for these allocators. Note + that this also implies changed allocation strategies for + all of these allocators. They will all now use the + "address order first fit carrier best fit" strategy.</p> + <p> + By passing <c>+Muacul 0</c> on the command line, all + configuration changes made by this change will be + reverted.</p> + <p> + Characteristics impact: Improved memory characteristics + with a smaller memory footprint at the expense of a quite + small performance cost.</p> + <p> + Own Id: OTP-11604 Aux Id: OTP-10279 </p> + </item> + <item> + <p>A clarification has been added to the documentation of + <c>-on_load()</c> in the Reference Manual that it is only + recommended for loading NIF libraries.</p> + <p> + Own Id: OTP-11611</p> + </item> + <item> + <p><c>+fnaw</c> is now default when starting the + emulator; it used to be <c>+fnl</c>.</p> + <p> + *** POTENTIAL INCOMPATIBILITY ***</p> + <p> + Own Id: OTP-11612</p> + </item> + <item> + <p> + EEP43: New data type - Maps</p> + <p> + With Maps you may for instance: <taglist> <item><c>M0 = + #{ a => 1, b => 2}, % create + associations</c></item> <item><c>M1 = M0#{ a := 10 }, % + update values</c></item> <item><c>M2 = M1#{ "hi" => + "hello"}, % add new associations</c></item> <item><c>#{ + "hi" := V1, a := V2, b := V3} = M2. % match keys with + values</c></item> </taglist></p> + <p> + For information on how to use Maps please see Map Expressions in the + <seealso marker="doc/reference_manual:expressions#map_expressions"> + Reference Manual</seealso>.</p> + <p> + The current implementation is without the following + features: <taglist> <item>No variable keys</item> + <item>No single value access</item> <item>No map + comprehensions</item> </taglist></p> + <p> + Note that Maps is <em>experimental</em> during OTP 17.0.</p> + <p> + Own Id: OTP-11616</p> + </item> + <item> + <p> + The previously deprecated driver API function + <c>driver_async_cancel()</c> has been removed. Due to + this, the driver API version has been bumped to 3.0.</p> + <p> + Thanks to Steve Vinoski.</p> + <p> + *** POTENTIAL INCOMPATIBILITY ***</p> + <p> + Own Id: OTP-11628</p> + </item> + <item> + <p> + Experimental "dirty scheduler" functionality has been + introduced. In order to try the functionality out, you + need to pass the command line argument + <c>--enable-dirty-schedulers</c> to <c>configure</c> when + building the system.</p> + <p> + Dirty schedulers can currently only be used by NIFs on a + system with SMP support. More information can be found in + the <seealso + marker="erl_nif#dirty_nifs"><c>erl_nif(3)</c></seealso> + documentation, the <seealso + marker="erl"><c>erl(1)</c></seealso> documentation, and + in the git commit comment of commit + 'c1c03ae4ee50e58b7669ea88ec4d29c6b2b67c7b'.</p> + <p> + Note that the functionality is <em>experimental</em>, and + <em>not supported</em>. This functionality <em>will</em> + be subject to backward incompatible changes. You should + <em>not</em> enable the dirty scheduler functionality on + production systems. It is only provided for testing.</p> + <p> + Thanks to Steve Vinoski.</p> + <p> + Own Id: OTP-11629</p> + </item> + <item> + <p> + Improve reduction cost and yielding of + <c>term_to_binary</c>. The reduction cost is increased + and garbage collection is disabled during yield.</p> + <p> + Impact: Improves system responsiveness when + <c>term_to_binary</c> is called with large terms without + significant degradation of single threaded performance.</p> + <p> + Own Id: OTP-11648 Aux Id: OTP-11388 </p> + </item> + <item> + <p> + By default, the system's version of zlib will be used, + provided its version is 1.2.4 or higher; otherwise the + built-in zlib will be used. The built-in version of zlib + has been bumped to 1.2.8. (Use the + <c>--enable-builtin-zlib</c> option to <c>configure</c> + to force the use of the built-in zlib.)</p> + <p> + Own Id: OTP-11669</p> + </item> + <item> + <p> + The default float encoding in binary_to_term and + external_size has been changed to use minor_mode 1 + instead of 0.</p> + <p> + *** POTENTIAL INCOMPATIBILITY ***</p> + <p> + Own Id: OTP-11738</p> + </item> + <item> + <p> + Introduced the <c>configure</c> option + <c>--with-assumed-cache-line-size=SIZE</c>. For more + information see <seealso + marker="doc/installation_guide:INSTALL"><c>$ERL_TOP/HOWTO/INSTALL.md</c></seealso>.</p> + <p> + Own Id: OTP-11742</p> + </item> + <item> + <p> + Halfword emulator is marked as deprecated. It still works + as before but is planned to be removed in a future major + release.</p> + <p> + Own Id: OTP-11777</p> + </item> + <item> + <p> + The external format for Maps has changed in a way that is + not compatible with the format used in OTP 17.0-rc1 and + OTP 17.0-rc2.</p> + <p> + *** POTENTIAL INCOMPATIBILITY ***</p> + <p> + Own Id: OTP-11782</p> + </item> + <item> + <p> + Fixed faulty make dependency that would make some make + versions fail while building gen_git_version.mk.</p> + <p> + Own Id: OTP-11784</p> + </item> + <item> + <p> + Introduced functionality for allowing old drivers and NIF + libraries to be loaded during a transition period. For + more information see <seealso + marker="erts:erl_driver#version_management">the version + management section in the <c>erl_driver(3)</c> + documentation</seealso> and <seealso + marker="erts:erl_nif#version_management">the version + management section in the <c>erl_nif(3)</c> + documentation</seealso>.</p> + <p> + Own Id: OTP-11799</p> + </item> + <item> + <p> + Support file paths longer than 259 characters on Windows. + Long absolute paths are automatically converted to UNC + format with a <c>\\?\</c> prefix which is the only way to + represent long paths. The 259 character limit still + applies for individual file names, relative paths and the + current working directory.</p> + <p> + Own Id: OTP-11813</p> + </item> + <item> + <p> + Document that escript:create/2 also accepts a 3-elements + tuple containing files and zip:create/3 options to build + a zip file.</p> + <p> + Thanks to Pierre Fenoll</p> + <p> + Own Id: OTP-11827</p> + </item> + <item> + <p> + Add systemd socket activation for epmd.</p> + <p> + Thanks to Matwey V. Kornilov</p> + <p> + Own Id: OTP-11829</p> + </item> + </list> + </section> + +</section> + +<section><title>Erts 5.10.4.1</title> + + <section><title>Known Bugs and Problems</title> + <list> + <item> + <p> + When using gen_tcp:connect and the <c>fd</c> option with + <c>port</c> and/or <c>ip</c>, the <c>port</c> and + <c>ip</c> options were ignored. This has been fixed so + that if <c>port</c> and/or <c>ip</c> is specified + together with <c>fd</c> a bind is requested for that + <c>fd</c>. If <c>port</c> and/or <c>ip</c> is not + specified bind will not be called.</p> + <p> + Own Id: OTP-12061</p> + </item> + </list> + </section> + +</section> + +<section><title>Erts 5.10.4</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> + When normalizing paths, erl_prim_loader would always + convert backslash to forward slash. This is correct on + Windows, but not on other operating systems. + erl_prim_loader now checks which OS is running before + performing this conversion.</p> + <p> + Own Id: OTP-11170</p> + </item> + <item> + <p> + Fixed syslog defines and defined LOG_ERR for systems + without syslog.h. Thanks to Matt Lewandowsky.</p> + <p> + Own Id: OTP-11349</p> + </item> + <item> + <p> + Check all pattern arguments passed to binary:matches/2. + Thanks to Mike Sassak.</p> + <p> + Own Id: OTP-11350</p> + </item> + <item> + <p> + Fix two small silent rules omissions. Thanks to Anthony + Ramine.</p> + <p> + Own Id: OTP-11351</p> + </item> + <item> + <p> + Teach configure to detect if posix_memalign cannot align + to more than the system page size. </p> + <p> + For cross-compiled systems a new environment variable + called erl_xcomp_posix_memalign has been introduced to + indicate whether posix_memalign should be used.</p> + <p> + Own Id: OTP-11371</p> + </item> + <item> + <p> + Fix bsr bug occurring when shifting a huge number a huge + number of bits to the right. Thanks to Lars Hesel + Christensen.</p> + <p> + Own Id: OTP-11381</p> + </item> + <item> + <p> + Fix memory leak for distributed monitors</p> + <p> + Own Id: OTP-11410</p> + </item> + <item> + <p> + Fix various typos in erts, kernel and ssh. Thanks to + Martin Hässler.</p> + <p> + Own Id: OTP-11414</p> + </item> + <item> + <p> + Crashdumps initiated by out-of-memory on process spawn + could cause the beam to segfault during crashdump writing + due to invalid pointers.</p> + <p> + The pointers are invalid since the process creation never + finished. This fix removes these processes from the + printouts. Reported by Richard Carlsson.</p> + <p> + Own Id: OTP-11420</p> + </item> + <item> + <p> + Crash dumps from 64-bit Erlang machines would have all + memory addresses truncated to 32 bits, which could cause + trouble inspecting processes message queues and stacks in + the crashdump viewer.</p> + <p> + Own Id: OTP-11450</p> + </item> + <item> + <p> + Threads other than schedulers threads could make thread + unsafe accesses when support for migration of memory + carriers had been enabled, i.e., when the <seealso + marker="erts_alloc#M_acul"><c>+M<S>acul</c></seealso> + command line flag had been passed to <seealso + marker="erl"><c>erl</c></seealso>. This could cause + corruption of the VMs internal state.</p> + <p> + This bug was introduced in erts-5.10.2 when the support + for migration of memory carriers was introduced.</p> + <p> + Own Id: OTP-11456 Aux Id: OTP-10279 </p> + </item> + <item> + <p> + Fix bug in <c>binary_to_term</c> for invalid bitstrings + and very large binaries (>2Gb).</p> + <p> + Own Id: OTP-11479</p> + </item> + <item> + <p> + Under rare circumstances a process calling <seealso + marker="kernel:inet#close/1"><c>inet:close/1</c></seealso>, + <seealso + marker="kernel:gen_tcp#close/1"><c>gen_tcp:close/1</c></seealso>, + <seealso + marker="kernel:gen_udp#close/1"><c>gen_udp:close/1</c></seealso>, + or <seealso + marker="kernel:gen_sctp#close/1"><c>gen_sctp:close/1</c></seealso> + could hang in the call indefinitely.</p> + <p> + Own Id: OTP-11491</p> + </item> + <item> + <p> + Fix bug that could cause a 32-bit emulator to always + crash at start (since R16B01) depending on the alignment + of static data in the beam executable.</p> + <p> + Own Id: OTP-11496</p> + </item> + <item> + <p> + Fix benign bugs regarding bitstring compare. Only a + nuisance for debug and valgrind VM.</p> + <p> + Own Id: OTP-11501</p> + </item> + <item> + <p> + Silence warnings (Thanks to Anthony Ramine)</p> + <p> + Own Id: OTP-11517</p> + </item> + <item> + <p> + The default wordsize of the emulator (beam) is now + determined by compiler default on Mac OSX (Darwin). This + was previously forced to 32bits by the configure script + unless otherwise specified.</p> + <p> + Own Id: OTP-11521</p> + </item> + </list> + </section> + + + <section><title>Improvements and New Features</title> + <list> + <item> + <p> + A new memory allocation feature called "super carrier" + has been introduced. The super carrier feature can be + used in different ways. It can for example be used for + pre-allocation of all memory that the runtime system + should be able to use.</p> + <p> + By default the super carrier is disabled. It is enabled + by passing the <seealso + marker="erts:erts_alloc#MMscs"><c>+MMscs <size in + MB></c></seealso> command line argument. For more + information see the documentation of the <seealso + marker="erts:erts_alloc#MMsco"><c>+MMsco</c></seealso>, + <seealso + marker="erts:erts_alloc#MMscrfsd"><c>+MMscrfsd</c></seealso>, + <seealso + marker="erts:erts_alloc#MMscrpm"><c>+MMscrpm</c></seealso>, + <seealso + marker="erts:erts_alloc#MMscs"><c>+MMscs</c></seealso>, + <seealso + marker="erts:erts_alloc#Musac"><c>+MMusac</c></seealso>, + and, <seealso + marker="erts:erts_alloc#Mlpm"><c>+Mlpm</c></seealso> + command line arguments in the <seealso + marker="erts:erts_alloc"><c>erts_alloc(3)</c></seealso> + documentation.</p> + <p> + Since it is disabled by default there should be no impact + on system characteristics if not used.</p> + <p> + This change has been marked as a potential + incompatibility since the returned list when calling + <seealso + marker="erts:erlang#system_info_allocator_tuple"><c>erlang:system_info({allocator, + mseg_alloc})</c></seealso> now also include an + <c>{erts_mmap, _}</c> tuple as one element in the list.</p> + <p> + *** POTENTIAL INCOMPATIBILITY ***</p> + <p> + Own Id: OTP-11149</p> + </item> + <item> + <p> + Added erlang:system_info(ets_limit) to provide a way to + retrieve the runtime's maximum number of ETS tables. + Thanks to Steve Vinoski</p> + <p> + Own Id: OTP-11362</p> + </item> + <item> + <p> + Add new BIF os:unsetenv/1 which deletes an environment + variable. Thanks to Martin Hässler.</p> + <p> + Own Id: OTP-11446</p> + </item> + <item> + <p> Introduced a new guarantee regarding exit signals + from ports: </p><p> If the process calling one of the + synchronous port BIFs listed below is linked to the port + identified by the first argument, and the port exits + before sending the result of the port operation, the exit + signal issued due to this link will be received by the + processes before the BIF returns, or fail with an + exception due to the port not being open. </p><p> The + synchronous port BIFs are: </p> <list> <item><seealso + marker="erlang#port_close/1"><c>port_close/1</c></seealso></item> + <item><seealso + marker="erlang#port_command/2"><c>port_command/2</c></seealso></item> + <item><seealso + marker="erlang#port_command/3"><c>port_command/3</c></seealso></item> + <item><seealso + marker="erlang#port_connect/2"><c>port_connect/2</c></seealso></item> + <item><seealso + marker="erlang#port_control/3"><c>port_control/3</c></seealso></item> + <item><seealso + marker="erlang#port_call/3"><c>erlang:port_call/3</c></seealso></item> + <item><seealso + marker="erlang#port_info/1"><c>erlang:port_info/1</c></seealso></item> + <item><seealso + marker="erlang#port_info/2"><c>erlang:port_info/2</c></seealso></item> + </list> <p> Note that some ports under certain + circumstances unlink themselves from the calling process + before exiting, i.e. even though the process linked + itself to the port there might be no link triggering an + exit signal. </p> <p>Characteristics impact: The return + or exception from the synchronous port BIF will be + delayed if the port simultaneously exit due to some issue + unrelated to the outstanding synchronous port BIF call. + In all other cases characteristics are unchanged. </p> + <p> + Own Id: OTP-11489</p> + </item> + </list> + </section> + +</section> + +<section><title>Erts 5.10.3.1</title> + + <section><title>Improvements and New Features</title> + <list> + <item> + <p> + Memory allocators will be able to create <c>sys_alloc</c> + carriers as fallback, if <c>mseg_alloc</c> cannot create + more carriers, on systems with <c>posix_memalign()</c> + support. This is similar to how it worked in pre-R16 + releases.</p> + <p> + Windows systems will create carriers using + <c>_aligned_malloc()</c> and can by this use the new + optimized allocator header scheme introduced in R16 on + other platforms.</p> + <p> + Own Id: OTP-11318</p> + </item> + </list> + </section> + +</section> + +<section><title>Erts 5.10.3</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> The documentation of predefined types and built-in + types has been corrected. </p> + <p> + Own Id: OTP-11090</p> + </item> + <item> + <p> + Fix changing terminal parameters in to_erl</p> + <p> + Change the behaviour of to_erl to use TCSADRAIN instead + of TCSANOW when changing terminal parameters. This makes + the serial driver wait for the output queues to be empty + before applying the terminal parameter change. Thanks to + Stefan Zegenhagen.</p> + <p> + Own Id: OTP-11206</p> + </item> + <item> + <p> + The default value of {flush, boolean()} in erlang:halt/2 + is documented to be 'true' if the status is an integer. + The implementation behaviour was reversed. The + Implementation is now corrected to adhere to the + documentation. Thanks to Jose Valim for reporting the + error.</p> + <p> + *** POTENTIAL INCOMPATIBILITY ***</p> + <p> + Own Id: OTP-11218</p> + </item> + <item> + <p> + Fix serious race bug in R16B01 that could cause PID + mix-ups when a lot of processes were spawned and + terminated in a very rapid pace on an SMP emulator with + at least two scheduler threads.</p> + <p> + Own Id: OTP-11225</p> + </item> + <item> + <p> + Validating a trace pattern with the option silent no + longer incorrectly enables/disables the silent option of + the calling process.</p> + <p> + Own Id: OTP-11232</p> + </item> + <item> + <p> + Fixed a bug where GCC 4.8 and later use a more aggressive + loop optimization algorithm that broke some previously + working code in the efile driver. Thanks to Tomas + Abrahamsson for reporting this issue.</p> + <p> + Own Id: OTP-11246</p> + </item> + <item> + <p> + Fixed bug when printing memory allocator acul option in + crash dump.</p> + <p> + Own Id: OTP-11264</p> + </item> + <item> + <p> + Opening a new compressed file on Windows could in rare + (random) cases result in {error,eisdir} or other error + codes although it should have succeeded. This is now + corrected.</p> + <p> + Own Id: OTP-11265</p> + </item> + <item> + <p> + Fixed a race condition when closing a trace port that + would cause the emulator to crash.</p> + <p> + Own Id: OTP-11290</p> + </item> + </list> + </section> + + + <section><title>Improvements and New Features</title> + <list> + <item> + <p> + There is a new somewhat experimental socket option + 'netns' that can set the network namespace for a socket + on Linux:es where it is supported. See the documentation.</p> + <p> + Own Id: OTP-11157</p> + </item> + <item> + <p> + New allocator strategy <c>aoffcbf</c> (address order + first fit carrier best fit). Supports carrier migration + but with better CPU performance than <c>aoffcaobf</c>.</p> + <p> + Own Id: OTP-11174</p> + </item> + <item> + <p> + Introduced functionality for inspection of system and + build configuration.</p> + <p> + Own Id: OTP-11196</p> + </item> + <item> + <p> + Fix matching of floating point middle-endian machines. + Thanks to Johannes Weissl.</p> + <p> + Own Id: OTP-11201</p> + </item> + <item> + <p> + Fix compile error on ARM and GCC versions greater than + 4.1.0. Thanks to Johannes Weissl.</p> + <p> + Own Id: OTP-11214</p> + </item> + <item> + <p> + run_erl: Redirect standard streams to /dev/null. Thanks + to Johannes Weissl.</p> + <p> + Own Id: OTP-11215</p> + </item> + <item> + <p> + Misc. corrections in documentation for erl_driver. Thanks + to Giacomo Olgeni.</p> + <p> + Own Id: OTP-11227</p> + </item> + <item> + <p> + Fix documentation regarding binary_part.</p> + <p> + Own Id: OTP-11239</p> + </item> + <item> + <p> + Make edlin understand a few important control keys. + Thanks to Stefan Zegenhagen.</p> + <p> + Own Id: OTP-11251</p> + </item> + <item> + <p> + Export type zlib:zstream/0. Thanks to Loic Hoguin.</p> + <p> + Own Id: OTP-11278</p> + </item> + <item> + <p> + Add erl option to set schedulers by percentages. </p> + <p> + For applications where measurements show enhanced + performance from the use of a non-default number of + emulator scheduler threads, having to accurately set the + right number of scheduler threads across multiple hosts + each with different numbers of logical processors is + difficult because the erl +S option requires absolute + numbers of scheduler threads and scheduler threads online + to be specified.</p> + <p> + To address this issue, add a +SP option to erl, similar + to the existing +S option but allowing the number of + scheduler threads and scheduler threads online to be set + as percentages of logical processors configured and + logical processors available, respectively. For example, + "+SP 50:25" sets the number of scheduler threads to 50% + of the logical processors configured, and the number of + scheduler threads online to 25% of the logical processors + available. The +SP option also interacts with any + settings specified with the +S option, such that the + combination of options "+S 4:4 +SP 50:50" (in either + order) results in 2 scheduler threads and 2 scheduler + threads online.</p> + <p> + Thanks to Steve Vinoski</p> + <p> + Own Id: OTP-11282</p> + </item> + <item> + <p> + Extend erl_driver interface with lock names</p> + <p> + Lock and thread names are already a feature in the driver + interface. This extension will let developers read these + names which eases debugging.</p> + <p> + Own Id: OTP-11303</p> + </item> + <item> + <p> + Fix incorrect values returned by integer_to_binary/2. + Thanks to Juan Jose Comellas.</p> + <p> + Own Id: OTP-11311</p> + </item> + <item> + <p> + Fix system_flag scheduling_statistics - disable . Thanks + to Steve Vinoski.</p> + <p> + Own Id: OTP-11317</p> + </item> + <item> + <p> The documentation of predefined types has been + corrected Thanks to Kostis Sagonas. </p> + <p> + Own Id: OTP-11321</p> + </item> + </list> + </section> + +</section> + <section><title>Erts 5.10.2</title> <section><title>Fixed Bugs and Malfunctions</title> @@ -321,7 +2501,7 @@ <item> <p> Support wide characters in the shell through wcwidth(). - Thanks to Anthony Ramine. Reported by Lo�c Hoguin.</p> + Thanks to Anthony Ramine. Reported by Loïc Hoguin.</p> <p> Own Id: OTP-11088</p> </item> @@ -342,7 +2522,7 @@ <item> <p> Remove 'query' from the list of reserved words in docs. - Thanks to Matthias Endler and Lo�c Hoguin.</p> + Thanks to Matthias Endler and Loïc Hoguin.</p> <p> Own Id: OTP-11158</p> </item> @@ -1961,7 +4141,7 @@ <item> <p> Fix typo in supervisor behaviour doc (Thanks to Ricardo - Catalinas Jim�nez)</p> + Catalinas Jiménez)</p> <p> Own Id: OTP-9924</p> </item> @@ -2225,7 +4405,7 @@ <item> <p> Fixes module erlang doc style: option description (Thanks - to Ricardo Catalinas Jim�nez)</p> + to Ricardo Catalinas Jiménez)</p> <p> Own Id: OTP-9697</p> </item> @@ -2674,7 +4854,7 @@ <item> <p> Fix typos in the epmd documentation (Thanks to Holger - Wei� )</p> + Weiß )</p> <p> Own Id: OTP-9387</p> </item> @@ -2779,7 +4959,7 @@ <item> <p> Fix non-existing function (erlang:disconnect/1) in - distributed reference manual (Thanks to Fabian Kr�l)</p> + distributed reference manual (Thanks to Fabian Król)</p> <p> Own Id: OTP-9504</p> </item> @@ -2807,7 +4987,7 @@ only separator characters (comma and space).</p> <p> The same applies to epmd's -address option.(Thanks to - Holger Wei�)</p> + Holger Weiß)</p> <p> Own Id: OTP-9525</p> </item> @@ -2951,7 +5131,7 @@ <p> Add support for querying the number of configured and online processors on SGI systems running IRIX.(Thanks to - Holger Wei�)</p> + Holger Weiß)</p> <p> Own Id: OTP-9531</p> </item> @@ -3061,7 +5241,7 @@ using a comma-separated list. If the loopback address is not in this list, it will be added implicitly, so that the daemon can be queried by an interactive epmd - process.(Thanks to Holger Wei�)</p> + process.(Thanks to Holger Weiß)</p> <p> Own Id: OTP-9213</p> </item> @@ -3096,7 +5276,7 @@ value over to dbg_gen_printf(). This fixes the problem that errno had been reset to zero by the time it was used (to print the corresponding error message) in the - dbg_gen_printf() function. (Thanks to Holger Wei�)</p> + dbg_gen_printf() function. (Thanks to Holger Weiß)</p> <p> Own Id: OTP-9223</p> </item> @@ -3482,7 +5662,7 @@ Mention that "-detached" implies "-noinput"</p> <p> Clarify that specifying "-noinput" is unnecessary if the - "-detached" flag is given. (thanks to Holger Wei�)</p> + "-detached" flag is given. (thanks to Holger Weiß)</p> <p> Own Id: OTP-9086</p> </item> @@ -3613,7 +5793,7 @@ <item> <p> The <c>configure</c> command line argument <seealso - marker="doc/installation_guide:INSTALL#How-to-Build-and-Install-ErlangOTP_A-Closer-Look-at-the-individual-Steps_Configuring">--enable-ethread-pre-pentium4-compatibility</seealso> + marker="doc/installation_guide:INSTALL#Advanced-configuration-and-build-of-ErlangOTP">--enable-ethread-pre-pentium4-compatibility</seealso> had no effect. This option is now also automatically enabled if required on the build machine.</p> <p> @@ -4192,7 +6372,7 @@ platforms than before. If <c>configure</c> warns about no atomic implementation available, try using the <c>libatomic_ops</c> library. Use the <seealso - marker="doc/installation_guide:INSTALL#How-to-Build-and-Install-ErlangOTP_A-Closer-Look-at-the-individual-Steps_Configuring">--with-libatomic_ops=PATH</seealso> + marker="doc/installation_guide:INSTALL#Advanced-configuration-and-build-of-ErlangOTP">--with-libatomic_ops=PATH</seealso> <c>configure</c> command line argument when specifying where the <c>libatomic_ops</c> installation is located. The <c>libatomic_ops</c> library can be downloaded from: @@ -4210,7 +6390,7 @@ the pentium 4 processor. If you want the runtime system to be compatible with older processors (back to 486) you need to pass the <seealso - marker="doc/installation_guide:INSTALL#How-to-Build-and-Install-ErlangOTP_A-Closer-Look-at-the-individual-Steps_Configuring">--enable-ethread-pre-pentium4-compatibility</seealso> + marker="doc/installation_guide:INSTALL#Advanced-configuration-and-build-of-ErlangOTP">--enable-ethread-pre-pentium4-compatibility</seealso> <c>configure</c> command line argument when configuring the system.</p> <p> @@ -4988,7 +7168,7 @@ failed to detect gcc C compilers with other command line names than gcc. `configure' now substitute GCC into the makefiles. If CC is a gcc C compiler, GCC will have the - value yes. (Thanks to Jean-S�bastien P�dron)</p> + value yes. (Thanks to Jean-Sébastien Pédron)</p> <p> Own Id: OTP-8373</p> </item> @@ -7358,7 +9538,7 @@ <p> IPv6 name resolving has now been fixed to use getaddrinfo() patch (thoroughly reworked) courtesy of Love - H�rnquist-�strand submitted by Fredrik Thulin. It also + Hörnquist-Åstrand submitted by Fredrik Thulin. It also can use gethostname2() patch (also reworked) courtesy of Mikael Magnusson for debian submitted by Sergei Golovan.</p> <p> diff --git a/erts/doc/src/notes_history.xml b/erts/doc/src/notes_history.xml index cc3b938c86..4420311912 100644 --- a/erts/doc/src/notes_history.xml +++ b/erts/doc/src/notes_history.xml @@ -1,10 +1,10 @@ -<?xml version="1.0" encoding="latin1" ?> +<?xml version="1.0" encoding="utf-8" ?> <!DOCTYPE chapter SYSTEM "chapter.dtd"> <chapter> <header> <copyright> - <year>2006</year><year>2009</year> + <year>2006</year><year>2013</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> diff --git a/erts/doc/src/part.xml b/erts/doc/src/part.xml index fa50329cad..7b17b5b551 100644 --- a/erts/doc/src/part.xml +++ b/erts/doc/src/part.xml @@ -1,4 +1,4 @@ -<?xml version="1.0" encoding="latin1" ?> +<?xml version="1.0" encoding="utf-8" ?> <!DOCTYPE part SYSTEM "part.dtd"> <part xmlns:xi="http://www.w3.org/2001/XInclude"> @@ -32,6 +32,7 @@ <p>The Erlang Runtime System Application <em>ERTS</em>.</p> </description> <xi:include href="communication.xml"/> + <xi:include href="time_correction.xml"/> <xi:include href="match_spec.xml"/> <xi:include href="crash_dump.xml"/> <xi:include href="alt_dist.xml"/> diff --git a/erts/doc/src/part_notes.xml b/erts/doc/src/part_notes.xml index 4f183999e6..b5c8f0af09 100644 --- a/erts/doc/src/part_notes.xml +++ b/erts/doc/src/part_notes.xml @@ -1,10 +1,10 @@ -<?xml version="1.0" encoding="latin1" ?> +<?xml version="1.0" encoding="utf-8" ?> <!DOCTYPE part SYSTEM "part.dtd"> <part xmlns:xi="http://www.w3.org/2001/XInclude"> <header> <copyright> - <year>2004</year><year>2009</year> + <year>2004</year><year>2013</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> diff --git a/erts/doc/src/part_notes_history.xml b/erts/doc/src/part_notes_history.xml index 1b9bcca773..a99fa4a17f 100644 --- a/erts/doc/src/part_notes_history.xml +++ b/erts/doc/src/part_notes_history.xml @@ -1,10 +1,10 @@ -<?xml version="1.0" encoding="latin1" ?> +<?xml version="1.0" encoding="utf-8" ?> <!DOCTYPE part SYSTEM "part.dtd"> <part xmlns:xi="http://www.w3.org/2001/XInclude"> <header> <copyright> - <year>2006</year><year>2009</year> + <year>2006</year><year>2013</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> diff --git a/erts/doc/src/ref_man.xml b/erts/doc/src/ref_man.xml index e55923c344..8ed7090a61 100644 --- a/erts/doc/src/ref_man.xml +++ b/erts/doc/src/ref_man.xml @@ -1,4 +1,4 @@ -<?xml version="1.0" encoding="latin1" ?> +<?xml version="1.0" encoding="utf-8" ?> <!DOCTYPE application SYSTEM "application.dtd"> <application xmlns:xi="http://www.w3.org/2001/XInclude"> diff --git a/erts/doc/src/run_erl.xml b/erts/doc/src/run_erl.xml index c9784299b3..28e94c6da8 100644 --- a/erts/doc/src/run_erl.xml +++ b/erts/doc/src/run_erl.xml @@ -1,10 +1,10 @@ -<?xml version="1.0" encoding="latin1" ?> +<?xml version="1.0" encoding="utf-8" ?> <!DOCTYPE comref SYSTEM "comref.dtd"> <comref> <header> <copyright> - <year>1999</year><year>2011</year> + <year>1999</year><year>2013</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -58,7 +58,7 @@ first argument to run_erl on the command line.</item> <tag>pipe_dir</tag> <item>This is where to put the named pipe, usually - <c><![CDATA[/tmp/]]></c>. It shall be suffixed by a <c><![CDATA[/]]></c> (slash), + <c><![CDATA[/tmp/]]></c> on Unix or <c><![CDATA[/pipe/]]></c> on OSE. It shall be suffixed by a <c><![CDATA[/]]></c> (slash), i.e. not <c><![CDATA[/tmp/epipies]]></c>, but <c><![CDATA[/tmp/epipes/]]></c>. </item> <tag>log_dir</tag> <item>This is where the log files are written. There will be one diff --git a/erts/doc/src/specs.xml b/erts/doc/src/specs.xml index e5c2f4783f..41a3984659 100644 --- a/erts/doc/src/specs.xml +++ b/erts/doc/src/specs.xml @@ -1,4 +1,4 @@ -<?xml version="1.0" encoding="latin1" ?> +<?xml version="1.0" encoding="utf-8" ?> <specs xmlns:xi="http://www.w3.org/2001/XInclude"> <xi:include href="../specs/specs_erl_prim_loader.xml"/> <xi:include href="../specs/specs_erlang.xml"/> diff --git a/erts/doc/src/start.xml b/erts/doc/src/start.xml index 5dc33deb2a..e9a5714f93 100644 --- a/erts/doc/src/start.xml +++ b/erts/doc/src/start.xml @@ -1,10 +1,10 @@ -<?xml version="1.0" encoding="latin1" ?> +<?xml version="1.0" encoding="utf-8" ?> <!DOCTYPE comref SYSTEM "comref.dtd"> <comref> <header> <copyright> - <year>1999</year><year>2009</year> + <year>1999</year><year>2013</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> diff --git a/erts/doc/src/start_erl.xml b/erts/doc/src/start_erl.xml index 92d87b095a..fe808f7737 100644 --- a/erts/doc/src/start_erl.xml +++ b/erts/doc/src/start_erl.xml @@ -1,10 +1,10 @@ -<?xml version="1.0" encoding="latin1" ?> +<?xml version="1.0" encoding="utf-8" ?> <!DOCTYPE comref SYSTEM "comref.dtd"> <comref> <header> <copyright> - <year>1998</year><year>2011</year> + <year>1998</year><year>2013</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> diff --git a/erts/doc/src/time_correction.xml b/erts/doc/src/time_correction.xml new file mode 100644 index 0000000000..7f7c28fc30 --- /dev/null +++ b/erts/doc/src/time_correction.xml @@ -0,0 +1,274 @@ +<?xml version="1.0" encoding="utf-8" ?> +<!DOCTYPE chapter SYSTEM "chapter.dtd"> + +<chapter> + <header> + <copyright> + <year>1999</year><year>2014</year> + <holder>Ericsson AB. All Rights Reserved.</holder> + </copyright> + <legalnotice> + The contents of this file are subject to the Erlang Public License, + Version 1.1, (the "License"); you may not use this file except in + compliance with the License. You should have received a copy of the + Erlang Public License along with this software. If not, it can be + retrieved online at http://www.erlang.org/. + + Software distributed under the License is distributed on an "AS IS" + basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See + the License for the specific language governing rights and limitations + under the License. + + </legalnotice> + + <title>Time and time correction in Erlang</title> + <prepared>Patrik Nyblom</prepared> + <responsible></responsible> + <docno></docno> + <approved></approved> + <checked></checked> + <date>2013-08-28</date> + <rev>PA1</rev> + <file>time_correction.xml</file> + </header> + <p>Time is vital to an Erlang program and, more importantly, <em>correct</em> + time is vital to an Erlang program. As Erlang is a language with + soft real time properties and we have the possibility to express + time in our programs, the Virtual Machine and the language has to be + very careful about what is considered a correct point in time and in + how time functions behave.</p> + + <p>In the beginning, Erlang was constructed assuming that the wall + clock time in the system showed a monotonic time moving forward at + exactly the same pace as the definition of time. That more or less + meant that an atomic clock (or better) was expected to be attached + to your hardware and that the hardware was then expected to be + locked away from any human (or unearthly) tinkering for all + eternity. While this might be a compelling thought, it's simply + never the case.</p> + + <p>A "normal" modern computer can not keep time. Not on itself and + not unless you actually have a chip level atomic clock wired to + it. Time, as perceived by your computer, will normally need to be + corrected. Hence the NTP protocol that together with the ntpd + process will do it's best to keep your computers time in sync with + the "real" time in the universe. Between NTP corrections, usually a + less potent time-keeper than an atomic clock is used.</p> + + <p>But NTP is not fail safe. The NTP server can be unavailable, the + ntp.conf can be wrongly configured or your computer may from time to + time be disconnected from the internet. Furthermore you can have a + user (or even system administrator) on your system that thinks the + right way to handle daylight saving time is to adjust the clock one + hour two times a year (a tip, that is not the right way to do + it...). To further complicate things, this user fetched your + software from the internet and has never ever thought about what's + the correct time as perceived by a computer. The user simply does + not care about keeping the wall clock in sync with the rest of the + universe. The user expects your program to have omnipotent knowledge + about the time.</p> + + <p>Most programmers also expect time to be reliable, at least until + they realize that the wall clock time on their workstation is of by + a minute. Then they simply set it to the correct time, maybe or + maybe not in a smooth way. Most probably not in a smooth way.</p> + + <p>The amount of problems that arise when you expect the wall clock + time on the system to always be correct may be immense. Therefore Erlang + introduced the "corrected estimate of time", or the "time + correction" many years ago. The time correction relies on the fact + that most operating systems have some kind of monotonic clock, + either a real time extension or some built in "tick counter" that is + independent of the wall clock settings. This counter may have + microsecond resolution or much less, but generally it has a drift + that is not to be ignored.</p> + + <p>So we have this monotonic ticking and we have the wall clock + time. Two unreliable times that together can give us an estimate of + an actual wall clock time that does not jump around and that + monotonically moves forward. If the tick counter has a high + resolution, this is fairly easy to do, if the counter has a low + resolution, it's more expensive, but still doable down to + frequencies of 50-60 Hz (of the tick counter).</p> + + <p>So the corrected time is the nearest approximation of an atomic + clock that is available on the computer. We want it to have the + following properties:</p> + <taglist> + <tag>Monotonic</tag> + <item>The clock should not move backwards</item> + <tag>Intervals should be near the truth</tag> + <item>We want the actual time (as measured by an atomic clock or + an astronomer) that passes between two time stamps, T1 and T2, to be as + near to T2 - T1 as possible.</item> + <tag>Tight coupling to the wall clock</tag> + <item>We want a timer that is to be fired when the wall clock + reaches a time in the future, to fire as near to that point in + time as possible</item> + </taglist> + <p>To meet all the criteria, we have to utilize both times in such a + way that Erlangs "corrected time" moves slightly slower or slightly + faster than the wall clock to get in sync with it. The word + "slightly" means a maximum of 1% difference to the wall clock time, + meaning that a sudden change in the wall clock of one minute, takes + 100 minutes to fix, by letting all "corrected time" move 1% slower + or faster.</p> + + <p>Needless to say, correcting for a faulty handling of daylight + saving time may be disturbing to a user comparing wall clock + time to for example calendar:now_to_local_time(erlang:now()). But + calendar:now_to_local_time/1 is not supposed to be used for presenting wall + clock time to the user.</p> + + <p>Time correction is not perfect, but it saves you from the havoc + of clocks jumping around, which would make timers in your program + fire far to late or far to early and could bring your whole system + to it's knees (or worse) just because someone detected a small error + in the wall clock time of the server where your program runs. So + while it might be confusing, it is still a really good feature of + Erlang and you should not throw it away using time functions which + may give you higher benchmark results, not unless you really know + what you're doing.</p> + + <section> + <title>What does time correction mean in my system?</title> + <p>Time correction means that Erlang estimates a time from current + and previous settings of the wall clock, and it uses a fairly + exact tick counter to detect when the wall clock time has jumped + for some reason, slowly adjusting to the new value.</p> + + <p>In practice, this means that the difference between two calls + to time corrected functions, like erlang:now(), might differ up to + one percent from the corresponding calls to non time corrected + functions (like os:timestamp()). Furthermore, if comparing + calendar:local_time/0 to calendar:now_to_local_time(erlang:now()), + you might temporarily see a difference, depending on how well kept your + system is.</p> + + <p>It is important to understand that it is (to the program) + always unknown if it is the wall clock time that moves in the + wrong pace or the Erlang corrected time. The only way to determine + that, is to have an external source of universally correct time. If + some such source is available, the wall clock time can be kept + nearly perfect at all times, and no significant difference will be + detected between erlang:now/0's pace and the wall clock's.</p> + + <p>Still, the time correction will mean that your system keeps + it's real time characteristics very well, even when the wall clock + is unreliable.</p> + </section> + <section> + <title>Where does Erlang use corrected time?</title> + <p>For all functionality where real time characteristics are + desirable, time correction is used. This basically means:</p> + <taglist> + <tag>erlang:now/0</tag> + <item>The infamous erlang:now/0 function uses time correction so + that differences between two "now-timestamps" will correspond to + other timeouts in the system. erlang:now/0 also holds other + properties, discussed later.</item> + <tag>receive ... after</tag> + <item>Timeouts on receive uses time correction to determine a + stable timeout interval.</item> + <tag>The timer module</tag> + <item>As the timer module uses other built in functions which + deliver corrected time, the timer module itself works with + corrected time.</item> + <tag>erlang:start_timer/3 and erlang:send_after/3</tag> + <item>The timer BIF's work with corrected time, so that they + will not fire prematurely or too late due to changes in the wall + clock time.</item> + </taglist> + + <p>All other functionality in the system where erlang:now/0 or any + other time corrected functionality is used, will of course + automatically benefit from it, as long as it's not "optimized" to + use some other time stamp function (like os:timestamp/0).</p> + + <p>Modules like calendar and functions like erlang:localtime/0 use + the wall clock time as it is currently set on the system. They + will not use corrected time. However, if you use a now-value and + convert it to local time, you will get a corrected local time + value, which may or may not be what you want. Typically older code + tend to use erlang:now/0 as a wall clock time, which is usually + correct (at least when testing), but might surprise you when + compared to other times in the system.</p> + </section> + <section> + <title>What is erlang:now/0 really?</title> + <p>erlang:now/0 is a function designed to serve multiple purposes + (or a multi-headed beast if you're a VM designer). It is expected + to hold the following properties:</p> + <taglist> + <tag>Monotonic</tag> + <item>erlang:now() never jumps backwards - it always moves + forward</item> + <tag>Interval correct</tag> + <item>The interval between two erlang:now() calls is expected to + correspond to the correct time in real life (as defined by an + atomic clock, or better)</item> + <tag>Absolute correctness</tag> + <item>The erlang:now/0 value should be possible to convert to an + absolute and correct date-time, corresponding to the real world + date and time (the wall clock)</item> + <tag>System correspondence</tag> + <item>The erlang:now/0 value converted to a date-time is + expected to correspond to times given by other programs on the + system (or by functions like os:timestamp/0)</item> + <tag>Unique</tag> + <item>No two calls to erlang:now on one Erlang node should + return the same value</item> + </taglist> + <p>All these requirements are possible to uphold at the same + time if (and only if):</p> + <taglist> + <tag>The wall clock time of the system is perfect</tag> + <item>The system (Operating System) time needs to be perfectly + in sync with the actual time as defined by an atomic clock or + a better time source. A good installation using NTP, and that is + up to date before Erlang starts, will have properties that for + most users and programs will be near indistinguishable from the + perfect time. Note that any larger corrections to the time done + by hand, or after Erlang has started, will partly (or + temporarily) invalidate some of the properties, as the time is + no longer perfect.</item> + <tag>Less than one call per microsecond to erlang:now/0 is + done</tag> + <item>This means that at <em>any</em> microsecond interval in + time, there can be no more than one call to erlang:now/0 in the + system. However, for the system not to loose it's properties + completely, it's enough that it on average is no more than one + call per microsecond (in one Erlang node).</item> + </taglist> + <p>The uniqueness property of erlang:now/0 is the most limiting + property. It means that erlang:now() maintains a global state and + that there is a hard-to-check property of the system that needs to + be maintained. For most applications this is still not a problem, + but a future system might very well manage to violate the + frequency limit on the calls globally. The uniqueness property is + also quite useless, as there are globally unique references that + provide a much better unique value to programs. However the + property will need to be maintained unless a really subtle + backward compatibility issue is to be introduced.</p> + </section> + <section> + <title>Should I use erlang:now/0 or os:timestamp/0</title> + <p>The simple answer is to use erlang:now/0 for everything where + you want to keep real time characteristics, but use os:timestamp + for things like logs, user communication and debugging (typically + timer:ts uses os:timestamp, as it is a test tool, not a real world + application API). The benefit of using os:timestamp/0 is that it's + faster and does not involve any global state (unless the operating + system has one). The downside is that it will be vulnerable to wall + clock time changes.</p> + </section> + <section> + <title>Turning off time correction</title> + <p>If, for some reason, time correction causes trouble and you are + absolutely confident that the wall clock on the system is nearly + perfect, you can turn off time correction completely by giving the + <c>+c</c> option to <c>erl</c>. The probability for this being a + good idea, is very low.</p> + </section> +</chapter> + diff --git a/erts/doc/src/tty.xml b/erts/doc/src/tty.xml index 7d662a2849..db15195f65 100644 --- a/erts/doc/src/tty.xml +++ b/erts/doc/src/tty.xml @@ -1,10 +1,10 @@ -<?xml version="1.0" encoding="latin1" ?> +<?xml version="1.0" encoding="utf-8" ?> <!DOCTYPE chapter SYSTEM "chapter.dtd"> <chapter> <header> <copyright> - <year>1996</year><year>2010</year> + <year>1996</year><year>2013</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -47,7 +47,7 @@ <section> <title>Normal Mode</title> <p>In normal mode keystrokes from the user are collected and interpreted by <c><![CDATA[tty]]></c>. Most of the <em>emacs</em> line editing commands are supported. The following is a complete list of the supported line editing commands.<br></br></p> - <p><em>Note:</em> The notation <c><![CDATA[C-a]]></c> means pressing the control key and the letter <c><![CDATA[a]]></c> simultaneously. <c><![CDATA[M-f]]></c> means pressing the <c><![CDATA[ESC]]></c> key followed by the letter <c><![CDATA[f]]></c>. + <p><em>Note:</em> The notation <c><![CDATA[C-a]]></c> means pressing the control key and the letter <c><![CDATA[a]]></c> simultaneously. <c><![CDATA[M-f]]></c> means pressing the <c><![CDATA[ESC]]></c> key followed by the letter <c><![CDATA[f]]></c>. <c><![CDATA[Home]]></c> and <c><![CDATA[End]]></c> represent the keys with the same name on the keyboard, whereas <c><![CDATA[Left]]></c> and <c><![CDATA[Right]]></c> represent the corresponding arrow keys. </p> <table> <row> @@ -55,6 +55,10 @@ <cell align="left" valign="middle"><em>Function</em></cell> </row> <row> + <cell align="left" valign="middle">Home</cell> + <cell align="left" valign="middle">Beginning of line</cell> + </row> + <row> <cell align="left" valign="middle">C-a</cell> <cell align="left" valign="middle">Beginning of line</cell> </row> @@ -63,6 +67,10 @@ <cell align="left" valign="middle">Backward character</cell> </row> <row> + <cell align="left" valign="middle">C-Left</cell> + <cell align="left" valign="middle">Backward word</cell> + </row> + <row> <cell align="left" valign="middle">M-b</cell> <cell align="left" valign="middle">Backward word</cell> </row> @@ -75,6 +83,10 @@ <cell align="left" valign="middle">Delete word</cell> </row> <row> + <cell align="left" valign="middle">End</cell> + <cell align="left" valign="middle">End of line</cell> + </row> + <row> <cell align="left" valign="middle">C-e</cell> <cell align="left" valign="middle">End of line</cell> </row> @@ -83,6 +95,10 @@ <cell align="left" valign="middle">Forward character</cell> </row> <row> + <cell align="left" valign="middle">C-Right</cell> + <cell align="left" valign="middle">Forward word</cell> + </row> + <row> <cell align="left" valign="middle">M-f</cell> <cell align="left" valign="middle">Forward word</cell> </row> @@ -95,6 +111,10 @@ <cell align="left" valign="middle">Kill line</cell> </row> <row> + <cell align="left" valign="middle">C-u</cell> + <cell align="left" valign="middle">Backward kill line</cell> + </row> + <row> <cell align="left" valign="middle">C-l</cell> <cell align="left" valign="middle">Redraw line</cell> </row> @@ -111,6 +131,10 @@ <cell align="left" valign="middle">Transpose characters</cell> </row> <row> + <cell align="left" valign="middle">C-w</cell> + <cell align="left" valign="middle">Backward kill word</cell> + </row> + <row> <cell align="left" valign="middle">C-y</cell> <cell align="left" valign="middle">Insert previously killed text</cell> </row> diff --git a/erts/doc/src/werl.xml b/erts/doc/src/werl.xml index 1494d91da8..49cc45e745 100644 --- a/erts/doc/src/werl.xml +++ b/erts/doc/src/werl.xml @@ -1,10 +1,10 @@ -<?xml version="1.0" encoding="latin1" ?> +<?xml version="1.0" encoding="utf-8" ?> <!DOCTYPE comref SYSTEM "comref.dtd"> <comref> <header> <copyright> - <year>1998</year><year>2009</year> + <year>1998</year><year>2013</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> diff --git a/erts/doc/src/zlib.xml b/erts/doc/src/zlib.xml index 8917ab5c3a..da8ccdecdf 100644 --- a/erts/doc/src/zlib.xml +++ b/erts/doc/src/zlib.xml @@ -1,10 +1,10 @@ -<?xml version="1.0" encoding="latin1" ?> +<?xml version="1.0" encoding="utf-8" ?> <!DOCTYPE erlref SYSTEM "erlref.dtd"> <erlref> <header> <copyright> - <year>2005</year><year>2011</year> + <year>2005</year><year>2013</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -161,20 +161,22 @@ list_to_binary([Compressed|Last])</pre> state. <c><anno>MemLevel</anno></c>=1 uses minimum memory but is slow and reduces compression ratio; <c><anno>MemLevel</anno></c>=9 uses maximum memory for optimal speed. The default value is 8.</p> - <p>The <c><anno>Strategy</anno></c> parameter is used to tune the - compression algorithm. Use the value <c>default</c> for - normal data, <c>filtered</c> for data produced by a filter - (or predictor), or <c>huffman_only</c> to force Huffman - encoding only (no string match). Filtered data consists - mostly of small values with a somewhat random - distribution. In this case, the compression algorithm is - tuned to compress them better. The effect of - <c>filtered</c>is to force more Huffman coding and less - string matching; it is somewhat intermediate between - <c>default</c> and <c>huffman_only</c>. The <c><anno>Strategy</anno></c> - parameter only affects the compression ratio but not the - correctness of the compressed output even if it is not set - appropriately.</p> + <p>The <c><anno>Strategy</anno></c> parameter is used to tune + the compression algorithm. Use the value <c>default</c> for + normal data, <c>filtered</c> for data produced by a filter (or + predictor), <c>huffman_only</c> to force Huffman encoding + only (no string match), or <c>rle</c> to limit match + distances to one (run-length encoding). Filtered data + consists mostly of small values with a somewhat random + distribution. In this case, the compression algorithm is tuned + to compress them better. The effect of <c>filtered</c>is to + force more Huffman coding and less string matching; it is + somewhat intermediate between <c>default</c> and + <c>huffman_only</c>. <c>rle</c> is designed to be almost as + fast as <c>huffman_only</c>, but give better compression for PNG + image data. The <c><anno>Strategy</anno></c> parameter only + affects the compression ratio but not the correctness of the + compressed output even if it is not set appropriately.</p> </desc> </func> <func> @@ -300,7 +302,7 @@ list_to_binary([B1,B2])</pre> <fsummary>Decompress data</fsummary> <desc> <p><c>inflate/2</c> decompresses as much data as possible. - It may some introduce some output latency (reading + It may introduce some output latency (reading input without producing any output).</p> <p>If a preset dictionary is needed at this point (see <c>inflateSetDictionary</c> below), <c>inflate/2</c> throws a |