diff options
Diffstat (limited to 'erts/doc/src')
40 files changed, 2109 insertions, 1060 deletions
diff --git a/erts/doc/src/Makefile b/erts/doc/src/Makefile index 89d7c85a86..d4c6fe67d2 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 diff --git a/erts/doc/src/absform.xml b/erts/doc/src/absform.xml index e512c19e05..4acc03b133 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> @@ -290,6 +290,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> 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 b3c4671c3d..c59741f250 100644 --- a/erts/doc/src/crash_dump.xml +++ b/erts/doc/src/crash_dump.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>2010</year> + <year>1999</year><year>2013</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -290,6 +290,10 @@ <em>Stack+heap</em>, <em>OldHeap</em>, <em>Heap unused</em> and <em>OldHeap unused</em> do not exist. Instead this field presents the size of the process' stack.</item> + <tag><em>Memory</em></tag> + <item>The total memory used by this process. This includes call stack, + heap and internal structures. Same as <seealso marker="erlang#process_info-2">erlang:process_info(Pid,memory)</seealso>. + </item> <tag><em>Program counter</em></tag> <item>The current instruction pointer. This is only interesting for runtime system developers. The function into which the program 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..48dfcb09b1 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> diff --git a/erts/doc/src/epmd.xml b/erts/doc/src/epmd.xml index 3e7005410f..963d35c3c8 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> diff --git a/erts/doc/src/erl.xml b/erts/doc/src/erl.xml index bb81330fec..bf0d132955 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> @@ -524,7 +524,7 @@ <p>Calling <c>erlang:halt/1</c> with a string argument will still produce 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> @@ -536,15 +536,35 @@ <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> </item> - <tag><c><![CDATA[+fnu]]></c></tag> + <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>By enabling Unicode file name translation on systems where this is not default, you open up to the possibility that some file names can not be interpreted by the VM and therefore will be returned to the program as raw binaries. The option is therefore considered experimental.</p> - </item> - <tag><c><![CDATA[+fna]]></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 filenames (use with care).</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 + sent to the <c>error_logger</c> whenever a wrongly encoded + file name is "skipped" in directory listings, <c>i</c> means + that those wrongly encoded file names are silently ignored and + <c>e</c> means that the API function will return an error + whenever a wrongly encoded file (or directory) name is + 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> + </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>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. + See the description of <c>+fnu</c> above. If the locale + 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> </item> <tag><c><![CDATA[+hms Size]]></c></tag> <item> @@ -571,9 +591,9 @@ </item> <tag><c><![CDATA[+L]]></c></tag> <item> - <p>Don't load information about source filenames and line numbers. + <p>Don't load information about source file names and line numbers. This will save some memory, but exceptions will not contain - information about the filenames and line numbers. + information about the file names and line numbers. </p> </item> <tag><marker id="erts_alloc"><c><![CDATA[+MFlag Value]]></c></marker></tag> @@ -615,7 +635,7 @@ debugging.</item> </taglist> </item> - <tag><marker id="+pc"/><marker id="max_processes"><c><![CDATA[+pc Range]]></c></marker></tag> + <tag><marker id="+pc"/><marker id="printable_character_range"><c><![CDATA[+pc Range]]></c></marker></tag> <item> <p>Sets the range of characters that the system will consider printable in heuristic detection of strings. This typically affects the shell, debugger and io:format functions (when ~tp is used in the format string).</p> <p>Currently two values for the <c>Range</c> are supported: @@ -637,10 +657,11 @@ <p>Se also <seealso marker="stdlib:io#printable_range/0"> io:printable_range/0</seealso>.</p> </item> - <tag><marker id="+P"/><marker id="max_processes"><c><![CDATA[+P Number]]></c></marker></tag> + <tag><marker id="+P"/><marker id="max_processes"><c><![CDATA[+P Number|legacy]]></c></marker></tag> <item> <p>Sets the maximum number of simultaneously existing processes for this - system. Valid range for <c>Number</c> is <c>[1024-134217727]</c></p> + system if a <c>Number</c> is passed as value. Valid range for + <c>Number</c> is <c>[1024-134217727]</c></p> <p><em>NOTE</em>: The actual maximum chosen may be much larger than the <c>Number</c> passed. Currently the runtime system often, but not always, chooses a value that is a power of 2. This might, @@ -648,11 +669,19 @@ checked by calling <seealso marker="erlang#system_info_process_limit">erlang:system_info(process_limit)</seealso>.</p> <p>The default value is <c>262144</c></p> + <p>If <c>legacy</c> is passed as value, the legacy algorithm for + allocation of process identifiers will be used. Using the legacy + algorithm, identifiers will be allocated in a strictly increasing + fashion until largest possible identifier has been reached. Note that + this algorithm suffers from performance issues and can under certain + circumstances be extremely expensive. The legacy algoritm is deprecated, + and the <c>legacy</c> option is scheduled for removal in OTP-R18.</p> </item> - <tag><marker id="+Q"/><marker id="max_ports"><c><![CDATA[+Q Number]]></c></marker></tag> + <tag><marker id="+Q"/><marker id="max_ports"><c><![CDATA[+Q Number|legacy]]></c></marker></tag> <item> <p>Sets the maximum number of simultaneously existing ports for this - system. Valid range for <c>Number</c> is <c>[1024-134217727]</c></p> + system if a Number is passed as value. Valid range for <c>Number</c> + is <c>[1024-134217727]</c></p> <p><em>NOTE</em>: The actual maximum chosen may be much larger than the actual <c>Number</c> passed. Currently the runtime system often, but not always, chooses a value that is a power of 2. This might, @@ -671,6 +700,13 @@ for setting the maximum number of simultaneously existing ports. This environment variable is deprecated, and scheduled for removal in OTP-R17, but can still be used.</p> + <p>If <c>legacy</c> is passed as value, the legacy algorithm for + allocation of port identifiers will be used. Using the legacy + algorithm, identifiers will be allocated in a strictly increasing + fashion until largest possible identifier has been reached. Note that + this algorithm suffers from performance issues and can under certain + circumstances be extremely expensive. The legacy algoritm is deprecated, + and the <c>legacy</c> option is scheduled for removal in OTP-R18.</p> </item> <tag><marker id="compat_rel"><c><![CDATA[+R ReleaseNumber]]></c></marker></tag> <item> @@ -712,19 +748,47 @@ </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>This flag will be ignored if the emulator doesn't have + <p>If <c>Schedulers</c> or <c>SchedulersOnline</c> is specified as a + negative number, the value is subtracted from the default number of + logical processors configured or logical processors available, respectively. + </p> + <p>Specifying the value 0 for <c>Schedulers</c> or <c>SchedulersOnline</c> + resets the number of scheduler threads or scheduler threads online respectively + to its default value. + </p> + <p>This option is ignored if the emulator doesn't have + SMP support enabled (see the <seealso marker="#smp">-smp</seealso> + flag).</p> + </item> + <tag><marker id="+SP"><c><![CDATA[+SP SchedulersPercentage:SchedulersOnlinePercentage]]></c></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 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> @@ -1001,6 +1065,20 @@ <p>For more information, see <seealso marker="erlang#system_info_cpu_topology">erlang:system_info(cpu_topology)</seealso>.</p> </item> + <tag><marker id="+sfwi"><c>+sfwi Interval</c></marker></tag> + <item> + <p>Set scheduler forced wakeup interval. All run queues will + be scanned each <c>Interval</c> milliseconds. While there are + sleeping schedulers in the system, one scheduler will be woken + for each non-empty run queue found. An <c>Interval</c> of zero + disables this feature, which also is the default. + </p> + <p>This feature has been introduced as a temporary workaround + for lengthy executing native code, and native code that do not + bump reductions properly in OTP. When these bugs have be fixed + the <c>+sfwi</c> flag will be removed. + </p> + </item> <tag><marker id="+stbt"><c>+stbt BindType</c></marker></tag> <item> <p>Try to set scheduler bind type. The same as the @@ -1009,6 +1087,20 @@ 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> + <item> + <p> + Set scheduler wake cleanup threshold. Default is <c>medium</c>. + This flag controls how eager schedulers should be requesting + wake up due to certain cleanup operations. When a lazy setting + is used, more outstanding cleanup operations can be left undone + while a scheduler is idling. When an eager setting is used, + schedulers will more frequently be woken, potentially increasing + CPU-utilization. + </p> + <p><em>NOTE:</em> This flag may be removed or changed at any time without prior notice. + </p> + </item> <tag><marker id="+sws"><c>+sws default|legacy</c></marker></tag> <item> <p> 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..b453a4861e 100644 --- a/erts/doc/src/erl_driver.xml +++ b/erts/doc/src/erl_driver.xml @@ -1,4 +1,4 @@ -<?xml version="1.0" encoding="latin1" ?> +<?xml version="1.0" encoding="utf-8" ?> <!DOCTYPE cref SYSTEM "cref.dtd"> <cref> @@ -666,7 +666,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> @@ -1014,7 +1014,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 @@ -1056,7 +1056,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 +1068,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 +1524,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> @@ -1758,7 +1758,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 @@ -1779,11 +1779,11 @@ ERL_DRV_EXT2TERM char *buf, ErlDrvUInt len 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 @@ -1879,7 +1879,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 +1937,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 +1981,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> @@ -1998,7 +1998,7 @@ ERL_DRV_EXT2TERM char *buf, ErlDrvUInt len The data should be freed in <c>async_free</c>, because it's called if <c>driver_async_cancel</c> is called.</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 @@ -2022,6 +2022,24 @@ ERL_DRV_EXT2TERM char *buf, ErlDrvUInt len </desc> </func> <func> + <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_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> <name><ret>int</ret><nametext>driver_async_cancel(long id)</nametext></name> <fsummary>Cancel an asynchronous call</fsummary> <desc> @@ -2033,10 +2051,10 @@ ERL_DRV_EXT2TERM char *buf, ErlDrvUInt len 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, + scheduled for removal in OTP-R17. 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><p><c>driver_async_cancel()</c> is deprecated and will + be removed in the OTP-R17 release.</p> </warning> </desc> @@ -2048,7 +2066,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 +2094,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 +2302,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 +2487,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 +2516,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 +2840,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 +2907,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 +2994,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..f91ed78122 100644 --- a/erts/doc/src/erl_ext_dist.xml +++ b/erts/doc/src/erl_ext_dist.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> @@ -1014,10 +1014,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_ext_fig.ps b/erts/doc/src/erl_ext_fig.ps deleted file mode 100644 index 2501dc3c05..0000000000 --- a/erts/doc/src/erl_ext_fig.ps +++ /dev/null @@ -1,153 +0,0 @@ -%!PS-Adobe-3.0 EPSF-2.0 -%%BoundingBox: 0 0 600 520 -%%Creator: mscgen 1 -%%EndComments -0.70 0.70 scale -0 0 moveto -0 520 lineto -600 520 lineto -600 0 lineto -closepath -clip -%PageTrailer -%Page: 1 1 -/Helvetica findfont -10 scalefont -setfont -0 520 translate -/mtrx matrix def -/ellipse - { /endangle exch def - /startangle exch def - /ydia exch def - /xdia exch def - /y exch def - /x exch def - /savematrix mtrx currentmatrix def - x y translate - xdia 2 div ydia 2 div scale - 0 0 1 startangle endangle arc - savematrix setmatrix -} def -150 -12 moveto (Client (or Node)) dup stringwidth pop 2 div neg 0 rmoveto show -450 -12 moveto (EPMD) dup stringwidth pop 2 div neg 0 rmoveto show -newpath 150 -20 moveto 150 -45 lineto stroke -newpath 450 -20 moveto 450 -45 lineto stroke -newpath 150 -32 moveto 450 -32 lineto stroke -newpath 450 -32 moveto 440 -38 lineto 440 -26 lineto closepath fill -270 -30 moveto (ALIVE2_REQ) show -newpath 150 -45 moveto 150 -70 lineto stroke -newpath 450 -45 moveto 450 -70 lineto stroke -[2] 0 setdash -newpath 450 -57 moveto 150 -57 lineto stroke -[] 0 setdash -newpath 150 -57 moveto 160 -63 lineto 160 -51 lineto closepath fill -267 -55 moveto (ALIVE2_RESP) show -[2] 0 setdash -newpath 150 -70 moveto 150 -95 lineto stroke -[] 0 setdash -[2] 0 setdash -newpath 450 -70 moveto 450 -95 lineto stroke -[] 0 setdash -newpath 150 -95 moveto 150 -120 lineto stroke -newpath 450 -95 moveto 450 -120 lineto stroke -newpath 150 -107 moveto 450 -107 lineto stroke -newpath 450 -107 moveto 440 -113 lineto 440 -101 lineto closepath fill -253 -105 moveto (ALIVE_CLOSE_REQ) show -[2] 0 setdash -newpath 150 -120 moveto 150 -145 lineto stroke -[] 0 setdash -[2] 0 setdash -newpath 450 -120 moveto 450 -145 lineto stroke -[] 0 setdash -newpath 150 -145 moveto 150 -170 lineto stroke -newpath 450 -145 moveto 450 -170 lineto stroke -newpath 150 -157 moveto 450 -157 lineto stroke -newpath 450 -157 moveto 440 -163 lineto 440 -151 lineto closepath fill -248 -155 moveto (PORT_PLEASE2_REQ) show -newpath 150 -170 moveto 150 -195 lineto stroke -newpath 450 -170 moveto 450 -195 lineto stroke -[2] 0 setdash -newpath 450 -182 moveto 150 -182 lineto stroke -[] 0 setdash -newpath 150 -182 moveto 160 -188 lineto 160 -176 lineto closepath fill -267 -180 moveto (PORT2_RESP) show -[2] 0 setdash -newpath 150 -195 moveto 150 -220 lineto stroke -[] 0 setdash -[2] 0 setdash -newpath 450 -195 moveto 450 -220 lineto stroke -[] 0 setdash -newpath 150 -220 moveto 150 -245 lineto stroke -newpath 450 -220 moveto 450 -245 lineto stroke -newpath 150 -232 moveto 450 -232 lineto stroke -newpath 450 -232 moveto 440 -238 lineto 440 -226 lineto closepath fill -269 -230 moveto (NAMES_REQ) show -newpath 150 -245 moveto 150 -270 lineto stroke -newpath 450 -245 moveto 450 -270 lineto stroke -[2] 0 setdash -newpath 450 -257 moveto 150 -257 lineto stroke -[] 0 setdash -newpath 150 -257 moveto 160 -263 lineto 160 -251 lineto closepath fill -266 -255 moveto (NAMES_RESP) show -[2] 0 setdash -newpath 150 -270 moveto 150 -295 lineto stroke -[] 0 setdash -[2] 0 setdash -newpath 450 -270 moveto 450 -295 lineto stroke -[] 0 setdash -newpath 150 -295 moveto 150 -320 lineto stroke -newpath 450 -295 moveto 450 -320 lineto stroke -newpath 150 -307 moveto 450 -307 lineto stroke -newpath 450 -307 moveto 440 -313 lineto 440 -301 lineto closepath fill -272 -305 moveto (DUMP_REQ) show -newpath 150 -320 moveto 150 -345 lineto stroke -newpath 450 -320 moveto 450 -345 lineto stroke -[2] 0 setdash -newpath 450 -332 moveto 150 -332 lineto stroke -[] 0 setdash -newpath 150 -332 moveto 160 -338 lineto 160 -326 lineto closepath fill -269 -330 moveto (DUMP_RESP) show -[2] 0 setdash -newpath 150 -345 moveto 150 -370 lineto stroke -[] 0 setdash -[2] 0 setdash -newpath 450 -345 moveto 450 -370 lineto stroke -[] 0 setdash -newpath 150 -370 moveto 150 -395 lineto stroke -newpath 450 -370 moveto 450 -395 lineto stroke -newpath 150 -382 moveto 450 -382 lineto stroke -newpath 450 -382 moveto 440 -388 lineto 440 -376 lineto closepath fill -277 -380 moveto (KILL_REQ) show -newpath 150 -395 moveto 150 -420 lineto stroke -newpath 450 -395 moveto 450 -420 lineto stroke -[2] 0 setdash -newpath 450 -407 moveto 150 -407 lineto stroke -[] 0 setdash -newpath 150 -407 moveto 160 -413 lineto 160 -401 lineto closepath fill -274 -405 moveto (KILL_RESP) show -[2] 0 setdash -newpath 150 -420 moveto 150 -445 lineto stroke -[] 0 setdash -[2] 0 setdash -newpath 450 -420 moveto 450 -445 lineto stroke -[] 0 setdash -newpath 150 -445 moveto 150 -470 lineto stroke -newpath 450 -445 moveto 450 -470 lineto stroke -newpath 150 -457 moveto 450 -457 lineto stroke -newpath 450 -457 moveto 440 -463 lineto 440 -451 lineto closepath fill -273 -455 moveto (STOP_REQ) show -newpath 150 -470 moveto 150 -495 lineto stroke -newpath 450 -470 moveto 450 -495 lineto stroke -[2] 0 setdash -newpath 450 -482 moveto 150 -482 lineto stroke -[] 0 setdash -newpath 150 -482 moveto 160 -488 lineto 160 -476 lineto closepath fill -260 -480 moveto (STOP_OK_RESP) show -newpath 150 -495 moveto 150 -520 lineto stroke -newpath 450 -495 moveto 450 -520 lineto stroke -[2] 0 setdash -newpath 450 -507 moveto 150 -507 lineto stroke -[] 0 setdash -newpath 150 -507 moveto 160 -513 lineto 160 -501 lineto closepath fill -250 -505 moveto (STOP_NOTOK_RESP) show diff --git a/erts/doc/src/erl_fix_alloc.ps b/erts/doc/src/erl_fix_alloc.ps deleted file mode 100644 index bf65d1556c..0000000000 --- a/erts/doc/src/erl_fix_alloc.ps +++ /dev/null @@ -1,646 +0,0 @@ -%!PS-Adobe-2.0 EPSF-2.0 -%%Title: erl_fix_alloc.fig -%%Creator: fig2dev Version 3.1 Patchlevel 2 -%%CreationDate: Tue May 20 11:10:33 1997 -%%For: jocke@akvavit (Joakim Greben|,ETX/B/DUP) -%Magnification: 1.00 -%%Orientation: Portrait -%%BoundingBox: 0 0 506 462 -%%Pages: 0 -%%BeginSetup -%%IncludeFeature: *PageSize A4 -%%EndSetup -%%EndComments -/MyAppDict 100 dict dup begin def -/$F2psDict 200 dict def -$F2psDict begin -$F2psDict /mtrx matrix put -/col-1 {0 setgray} bind def -/col0 {0.000 0.000 0.000 srgb} bind def -/col1 {0.000 0.000 1.000 srgb} bind def -/col2 {0.000 1.000 0.000 srgb} bind def -/col3 {0.000 1.000 1.000 srgb} bind def -/col4 {1.000 0.000 0.000 srgb} bind def -/col5 {1.000 0.000 1.000 srgb} bind def -/col6 {1.000 1.000 0.000 srgb} bind def -/col7 {1.000 1.000 1.000 srgb} bind def -/col8 {0.000 0.000 0.560 srgb} bind def -/col9 {0.000 0.000 0.690 srgb} bind def -/col10 {0.000 0.000 0.820 srgb} bind def -/col11 {0.530 0.810 1.000 srgb} bind def -/col12 {0.000 0.560 0.000 srgb} bind def -/col13 {0.000 0.690 0.000 srgb} bind def -/col14 {0.000 0.820 0.000 srgb} bind def -/col15 {0.000 0.560 0.560 srgb} bind def -/col16 {0.000 0.690 0.690 srgb} bind def -/col17 {0.000 0.820 0.820 srgb} bind def -/col18 {0.560 0.000 0.000 srgb} bind def -/col19 {0.690 0.000 0.000 srgb} bind def -/col20 {0.820 0.000 0.000 srgb} bind def -/col21 {0.560 0.000 0.560 srgb} bind def -/col22 {0.690 0.000 0.690 srgb} bind def -/col23 {0.820 0.000 0.820 srgb} bind def -/col24 {0.500 0.190 0.000 srgb} bind def -/col25 {0.630 0.250 0.000 srgb} bind def -/col26 {0.750 0.380 0.000 srgb} bind def -/col27 {1.000 0.500 0.500 srgb} bind def -/col28 {1.000 0.630 0.630 srgb} bind def -/col29 {1.000 0.750 0.750 srgb} bind def -/col30 {1.000 0.880 0.880 srgb} bind def -/col31 {1.000 0.840 0.000 srgb} bind def - -end -save --18.0 481.0 translate -1 -1 scale -.9 .9 scale % to make patterns same scale as in xfig - -% This junk string is used by the show operators -/PATsstr 1 string def -/PATawidthshow { % cx cy cchar rx ry string - % Loop over each character in the string - { % cx cy cchar rx ry char - % Show the character - dup % cx cy cchar rx ry char char - PATsstr dup 0 4 -1 roll put % cx cy cchar rx ry char (char) - false charpath % cx cy cchar rx ry char - /clip load PATdraw - % Move past the character (charpath modified the - % current point) - currentpoint % cx cy cchar rx ry char x y - newpath - moveto % cx cy cchar rx ry char - % Reposition by cx,cy if the character in the string is cchar - 3 index eq { % cx cy cchar rx ry - 4 index 4 index rmoveto - } if - % Reposition all characters by rx ry - 2 copy rmoveto % cx cy cchar rx ry - } forall - pop pop pop pop pop % - - currentpoint - newpath - moveto -} bind def -/PATcg { - 7 dict dup begin - /lw currentlinewidth def - /lc currentlinecap def - /lj currentlinejoin def - /ml currentmiterlimit def - /ds [ currentdash ] def - /cc [ currentrgbcolor ] def - /cm matrix currentmatrix def - end -} bind def -% PATdraw - calculates the boundaries of the object and -% fills it with the current pattern -/PATdraw { % proc - save exch - PATpcalc % proc nw nh px py - 5 -1 roll exec % nw nh px py - newpath - PATfill % - - restore -} bind def -% PATfill - performs the tiling for the shape -/PATfill { % nw nh px py PATfill - - PATDict /CurrentPattern get dup begin - setfont - % Set the coordinate system to Pattern Space - PatternGState PATsg - % Set the color for uncolored pattezns - PaintType 2 eq { PATDict /PColor get PATsc } if - % Create the string for showing - 3 index string % nw nh px py str - % Loop for each of the pattern sources - 0 1 Multi 1 sub { % nw nh px py str source - % Move to the starting location - 3 index 3 index % nw nh px py str source px py - moveto % nw nh px py str source - % For multiple sources, set the appropriate color - Multi 1 ne { dup PC exch get PATsc } if - % Set the appropriate string for the source - 0 1 7 index 1 sub { 2 index exch 2 index put } for pop - % Loop over the number of vertical cells - 3 index % nw nh px py str nh - { % nw nh px py str - currentpoint % nw nh px py str cx cy - 2 index show % nw nh px py str cx cy - YStep add moveto % nw nh px py str - } repeat % nw nh px py str - } for - 5 { pop } repeat - end -} bind def - -% PATkshow - kshow with the current pattezn -/PATkshow { % proc string - exch bind % string proc - 1 index 0 get % string proc char - % Loop over all but the last character in the string - 0 1 4 index length 2 sub { - % string proc char idx - % Find the n+1th character in the string - 3 index exch 1 add get % string proe char char+1 - exch 2 copy % strinq proc char+1 char char+1 char - % Now show the nth character - PATsstr dup 0 4 -1 roll put % string proc chr+1 chr chr+1 (chr) - false charpath % string proc char+1 char char+1 - /clip load PATdraw - % Move past the character (charpath modified the current point) - currentpoint newpath moveto - % Execute the user proc (should consume char and char+1) - mark 3 1 roll % string proc char+1 mark char char+1 - 4 index exec % string proc char+1 mark... - cleartomark % string proc char+1 - } for - % Now display the last character - PATsstr dup 0 4 -1 roll put % string proc (char+1) - false charpath % string proc - /clip load PATdraw - neewath - pop pop % - -} bind def -% PATmp - the makepattern equivalent -/PATmp { % patdict patmtx PATmp patinstance - exch dup length 7 add % We will add 6 new entries plus 1 FID - dict copy % Create a new dictionary - begin - % Matrix to install when painting the pattern - TilingType PATtcalc - /PatternGState PATcg def - PatternGState /cm 3 -1 roll put - % Check for multi pattern sources (Level 1 fast color patterns) - currentdict /Multi known not { /Multi 1 def } if - % Font dictionary definitions - /FontType 3 def - % Create a dummy encoding vector - /Encoding 256 array def - 3 string 0 1 255 { - Encoding exch dup 3 index cvs cvn put } for pop - /FontMatrix matrix def - /FontBBox BBox def - /BuildChar { - mark 3 1 roll % mark dict char - exch begin - Multi 1 ne {PaintData exch get}{pop} ifelse % mark [paintdata] - PaintType 2 eq Multi 1 ne or - { XStep 0 FontBBox aload pop setcachedevice } - { XStep 0 setcharwidth } ifelse - currentdict % mark [paintdata] dict - /PaintProc load % mark [paintdata] dict paintproc - end - gsave - false PATredef exec true PATredef - grestore - cleartomark % - - } bind def - currentdict - end % newdict - /foo exch % /foo newlict - definefont % newfont -} bind def -% PATpcalc - calculates the starting point and width/height -% of the tile fill for the shape -/PATpcalc { % - PATpcalc nw nh px py - PATDict /CurrentPattern get begin - gsave - % Set up the coordinate system to Pattern Space - % and lock down pattern - PatternGState /cm get setmatrix - BBox aload pop pop pop translate - % Determine the bounding box of the shape - pathbbox % llx lly urx ury - grestore - % Determine (nw, nh) the # of cells to paint width and height - PatHeight div ceiling % llx lly urx qh - 4 1 roll % qh llx lly urx - PatWidth div ceiling % qh llx lly qw - 4 1 roll % qw qh llx lly - PatHeight div floor % qw qh llx ph - 4 1 roll % ph qw qh llx - PatWidth div floor % ph qw qh pw - 4 1 roll % pw ph qw qh - 2 index sub cvi abs % pw ph qs qh-ph - exch 3 index sub cvi abs exch % pw ph nw=qw-pw nh=qh-ph - % Determine the starting point of the pattern fill - %(px, py) - 4 2 roll % nw nh pw ph - PatHeight mul % nw nh pw py - exch % nw nh py pw - PatWidth mul exch % nw nh px py - end -} bind def - -% Save the original routines so that we can use them later on -/oldfill /fill load def -/oldeofill /eofill load def -/oldstroke /stroke load def -/oldshow /show load def -/oldashow /ashow load def -/oldwidthshow /widthshow load def -/oldawidthshow /awidthshow load def -/oldkshow /kshow load def - -% These defs are necessary so that subsequent procs don't bind in -% the originals -/fill { oldfill } bind def -/eofill { oldeofill } bind def -/stroke { oldstroke } bind def -/show { oldshow } bind def -/ashow { oldashow } bind def -/widthshow { oldwidthshow } bind def -/awidthshow { oldawidthshow } bind def -/kshow { oldkshow } bind def -/PATredef { - MyAppDict begin - { - /fill { /clip load PATdraw newpath } bind def - /eofill { /eoclip load PATdraw newpath } bind def - /stroke { PATstroke } bind def - /show { 0 0 null 0 0 6 -1 roll PATawidthshow } bind def - /ashow { 0 0 null 6 3 roll PATawidthshow } - bind def - /widthshow { 0 0 3 -1 roll PATawidthshow } - bind def - /awidthshow { PATawidthshow } bind def - /kshow { PATkshow } bind def - } { - /fill { oldfill } bind def - /eofill { oldeofill } bind def - /stroke { oldstroke } bind def - /show { oldshow } bind def - /ashow { oldashow } bind def - /widthshow { oldwidthshow } bind def - /awidthshow { oldawidthshow } bind def - /kshow { oldkshow } bind def - } ifelse - end -} bind def -false PATredef -% Conditionally define setcmykcolor if not available -/setcmykcolor where { pop } { - /setcmykcolor { - 1 sub 4 1 roll - 3 { - 3 index add neg dup 0 lt { pop 0 } if 3 1 roll - } repeat - setrgbcolor - pop - } bind def -} ifelse -/PATsc { % colorarray - aload length % c1 ... cn length - dup 1 eq { pop setgray } { 3 eq { setrgbcolor } { setcmykcolor - } ifelse } ifelse -} bind def -/PATsg { % dict - begin - lw setlinewidth - lc setlinecap - lj setlinejoin - ml setmiterlimit - ds aload pop setdash - cc aload pop setrgbcolor - cm setmatrix - end -} bind def - -/PATDict 3 dict def -/PATsp { - true PATredef - PATDict begin - /CurrentPattern exch def - % If it's an uncolored pattern, save the color - CurrentPattern /PaintType get 2 eq { - /PColor exch def - } if - /CColor [ currentrgbcolor ] def - end -} bind def -% PATstroke - stroke with the current pattern -/PATstroke { - countdictstack - save - mark - { - currentpoint strokepath moveto - PATpcalc % proc nw nh px py - clip newpath PATfill - } stopped { - (*** PATstroke Warning: Path is too complex, stroking - with gray) = - cleartomark - restore - countdictstack exch sub dup 0 gt - { { end } repeat } { pop } ifelse - gsave 0.5 setgray oldstroke grestore - } { pop restore pop } ifelse - newpath -} bind def -/PATtcalc { % modmtx tilingtype PATtcalc tilematrix - % Note: tiling types 2 and 3 are not supported - gsave - exch concat % tilingtype - matrix currentmatrix exch % cmtx tilingtype - % Tiling type 1 and 3: constant spacing - 2 ne { - % Distort the pattern so that it occupies - % an integral number of device pixels - dup 4 get exch dup 5 get exch % tx ty cmtx - XStep 0 dtransform - round exch round exch % tx ty cmtx dx.x dx.y - XStep div exch XStep div exch % tx ty cmtx a b - 0 YStep dtransform - round exch round exch % tx ty cmtx a b dy.x dy.y - YStep div exch YStep div exch % tx ty cmtx a b c d - 7 -3 roll astore % { a b c d tx ty } - } if - grestore -} bind def -/PATusp { - false PATredef - PATDict begin - CColor PATsc - end -} bind def - -% right30 -11 dict begin -/PaintType 1 def -/PatternType 1 def -/TilingType 1 def -/BBox [0 0 1 1] def -/XStep 1 def -/YStep 1 def -/PatWidth 1 def -/PatHeight 1 def -/Multi 2 def -/PaintData [ - { clippath } bind - { 32 16 true [ 32 0 0 -16 0 16 ] - {<00030003000c000c0030003000c000c0030003000c000c00 - 30003000c000c00000030003000c000c0030003000c000c0 - 030003000c000c0030003000c000c000>} - imagemask } bind -] def -/PaintProc { - pop - exec fill -} def -currentdict -end -/P2 exch def -1.1111 1.1111 scale %restore scale - -/cp {closepath} bind def -/ef {eofill} bind def -/gr {grestore} bind def -/gs {gsave} bind def -/sa {save} bind def -/rs {restore} bind def -/l {lineto} bind def -/m {moveto} bind def -/rm {rmoveto} bind def -/n {newpath} bind def -/s {stroke} bind def -/sh {show} bind def -/slc {setlinecap} bind def -/slj {setlinejoin} bind def -/slw {setlinewidth} bind def -/srgb {setrgbcolor} bind def -/rot {rotate} bind def -/sc {scale} bind def -/sd {setdash} bind def -/ff {findfont} bind def -/sf {setfont} bind def -/scf {scalefont} bind def -/sw {stringwidth} bind def -/tr {translate} bind def -/tnt {dup dup currentrgbcolor - 4 -2 roll dup 1 exch sub 3 -1 roll mul add - 4 -2 roll dup 1 exch sub 3 -1 roll mul add - 4 -2 roll dup 1 exch sub 3 -1 roll mul add srgb} - bind def -/shd {dup dup currentrgbcolor 4 -2 roll mul 4 -2 roll mul - 4 -2 roll mul srgb} bind def - /DrawSplineSection { - /y3 exch def - /x3 exch def - /y2 exch def - /x2 exch def - /y1 exch def - /x1 exch def - /xa x1 x2 x1 sub 0.666667 mul add def - /ya y1 y2 y1 sub 0.666667 mul add def - /xb x3 x2 x3 sub 0.666667 mul add def - /yb y3 y2 y3 sub 0.666667 mul add def - x1 y1 lineto - xa ya xb yb x3 y3 curveto - } def - -/$F2psBegin {$F2psDict begin /$F2psEnteredState save def} def -/$F2psEnd {$F2psEnteredState restore end} def -%%EndProlog - -$F2psBegin -10 setmiterlimit -n 0 842 m 0 0 l 595 0 l 595 842 l cp clip - 0.06000 0.06000 sc -7.500 slw -% Polyline -n 750 3600 m 750 1200 l 2325 1200 l 2325 3600 l gs col-1 s gr -% Polyline -n 750 1500 m 2325 1500 l gs col-1 s gr -% Polyline -n 750 1800 m 2325 1800 l gs col-1 s gr -15.000 slw -% Polyline -n 375 2100 m 2775 2100 l gs col-1 s gr -/Times-Roman ff 180.00 scf sf -900 2025 m -gs 1 -1 sc (allocated_blocks) col-1 sh gr -/Times-Roman ff 180.00 scf sf -1200 1725 m -gs 1 -1 sc (free_list) col-1 sh gr -/Times-Roman ff 180.00 scf sf -1200 1425 m -gs 1 -1 sc (item_size) col-1 sh gr -7.500 slw -% Polyline -n 3525 1200 m 5025 1200 l 5025 1800 l 3525 1800 l cp gs col-1 s gr -% Polyline -n 3525 1500 m 5025 1500 l gs col-1 s gr -/Times-Roman ff 180.00 scf sf -4050 1425 m -gs 1 -1 sc (next) col-1 sh gr -/Times-Roman ff 180.00 scf sf -4050 1725 m -gs 1 -1 sc (block) col-1 sh gr -% Polyline -n 5850 1200 m 7350 1200 l 7350 1800 l 5850 1800 l cp gs col-1 s gr -% Polyline -n 5850 1500 m 7350 1500 l gs col-1 s gr -/Times-Roman ff 180.00 scf sf -6375 1425 m -gs 1 -1 sc (next) col-1 sh gr -/Times-Roman ff 180.00 scf sf -6375 1725 m -gs 1 -1 sc (block) col-1 sh gr -15.000 slw -% Polyline - [100.0] 0 sd -n 3450 5700 m 5400 5700 l gs col-1 s gr [] 0 sd -7.500 slw -% Polyline -n 3600 8000 m 3600 3450 l 5175 3450 l 5175 8000 l gs col-1 s gr -15.000 slw -% Polyline - [100.0] 0 sd -n 3525 6900 m 5325 6900 l gs col-1 s gr [] 0 sd -0.000 slw -% Polyline - [33.3] 0 sd -n 3675 3525 m 5100 3525 l 5100 4425 l 3675 4425 l cp gs /PC [[1.00 1.00 1.00] [0.00 0.00 0.00]] def -15.00 15.00 sc P2 [16 0 0 -8 245.00 235.00] PATmp PATsp ef gr PATusp [] 0 sd -% Polyline - [33.3] 0 sd -n 3675 5775 m 5100 5775 l 5100 6825 l 3675 6825 l cp gs /PC [[1.00 1.00 1.00] [0.00 0.00 0.00]] def -15.00 15.00 sc P2 [16 0 0 -8 245.00 385.00] PATmp PATsp ef gr PATusp [] 0 sd -7.500 slw -% Polyline - [15 50.0] 50.0 sd -n 3600 4725 m 5250 4725 l gs col-1 s gr [] 0 sd -% Polyline - [15 50.0] 50.0 sd -n 3600 4950 m 5175 4950 l gs col-1 s gr [] 0 sd -0.000 slw -% Polyline - [15 25.0] 25.0 sd -n 6375 3750 m 6675 3750 l 6675 4050 l 6375 4050 l cp gs /PC [[1.00 1.00 1.00] [0.00 0.00 0.00]] def -15.00 15.00 sc P2 [16 0 0 -8 425.00 250.00] PATmp PATsp ef gr PATusp [] 0 sd -7.500 slw -% Polyline -gs clippath -4305 3253 m 4275 3373 l 4245 3253 l 4245 3415 l 4305 3415 l cp clip -n 4275 1800 m 4275 3400 l gs col-1 s gr gr - -% arrowhead -n 4305 3253 m 4275 3373 l 4245 3253 l 4275 3253 l 4305 3253 l cp gs 0.00 setgray ef gr col-1 s -15.000 slw -% Polyline - [100.0] 0 sd -n 3450 4500 m 5325 4500 l gs col-1 s gr [] 0 sd -7.500 slw -% Polyline -gs clippath -6630 2778 m 6600 2898 l 6570 2778 l 6570 2940 l 6630 2940 l cp clip -n 6600 1800 m 6600 2925 l gs col-1 s gr gr - -% arrowhead -n 6630 2778 m 6600 2898 l 6570 2778 l 6600 2778 l 6630 2778 l cp gs 0.00 setgray ef gr col-1 s -15.000 slw -% Polyline -gs clippath -656 840 m 723 1078 l 552 900 l 713 1181 l 817 1121 l cp clip -n 450 600 m 750 1125 l gs col-1 s gr gr - -% arrowhead -n 656 840 m 723 1078 l 552 900 l 604 870 l 656 840 l cp gs 0.00 setgray ef gr col-1 s -% Open spline -gs clippath -5627 1227 m 5749 1210 l 5650 1282 l 5800 1222 l 5778 1167 l cp clip -7.500 slw -n 4875.0 1350.0 m 5137.5 1350.0 l - 5137.5 1350.0 5400.0 1350.0 5587.5 1275.0 DrawSplineSection - 5775.0 1200.0 l gs col-1 s gr - gr - -% arrowhead -n 5627 1227 m 5749 1210 l 5650 1282 l 5639 1255 l 5627 1227 l cp gs 0.00 setgray ef gr col-1 s -% Open spline -gs clippath -7877 1227 m 7999 1210 l 7900 1282 l 8050 1222 l 8028 1167 l cp clip -n 7125.0 1350.0 m 7387.5 1350.0 l - 7387.5 1350.0 7650.0 1350.0 7837.5 1275.0 DrawSplineSection - 8025.0 1200.0 l gs col-1 s gr - gr - -% arrowhead -n 7877 1227 m 7999 1210 l 7900 1282 l 7889 1255 l 7877 1227 l cp gs 0.00 setgray ef gr col-1 s -% Interp Spline -gs clippath -3308 4453 m 3423 4496 l 3300 4512 l 3461 4532 l 3468 4472 l cp clip -n 2175 1650 m - 2346.9 1637.5 2421.9 1637.5 2475 1650 curveto - 2514.6 1659.3 2593.0 1702.0 2625 1725 curveto - 2665.4 1754.1 2753.1 1822.2 2775 1875 curveto - 2790.5 1912.4 2775.0 1990.8 2775 2025 curveto - 2775.0 2537.6 2542.8 3714.4 2775 4275 curveto - 2785.9 4301.4 2829.8 4335.4 2850 4350 curveto - 2882.0 4373.0 2962.7 4412.9 3000 4425 curveto - 3076.1 4449.8 3188.6 4468.5 3450 4500 curveto - gs col-1 s gr - gr - -% arrowhead -n 3308 4453 m 3423 4496 l 3300 4512 l 3304 4483 l 3308 4453 l cp gs 0.00 setgray ef gr col-1 s -% Interp Spline -gs clippath -5325 6973 m 5201 6969 l 5312 6914 l 5154 6949 l 5167 7007 l cp clip -n 5100 4575 m - 5270.9 4558.6 5345.9 4558.6 5400 4575 curveto - 5465.1 4594.7 5582.7 4669.6 5625 4725 curveto - 5662.1 4773.6 5691.1 4895.0 5700 4950 curveto - 5764.9 5350.0 5796.1 6267.8 5700 6675 curveto - 5690.7 6714.6 5655.4 6794.6 5625 6825 curveto - 5594.6 6855.4 5511.4 6886.6 5475 6900 curveto - 5424.7 6918.6 5349.7 6937.4 5175 6975 curveto - gs col-1 s gr - gr - -% arrowhead -n 5325 6973 m 5201 6969 l 5312 6914 l 5319 6944 l 5325 6973 l cp gs 0.00 setgray ef gr col-1 s -% Interp Spline -gs clippath -3300 1202 m 3423 1205 l 3313 1261 l 3471 1226 l 3458 1168 l cp clip -n 2250 1950 m - 2378.9 1959.4 2435.2 1959.4 2475 1950 curveto - 2514.6 1940.7 2593.0 1898.0 2625 1875 curveto - 2665.4 1845.9 2745.9 1765.4 2775 1725 curveto - 2821.1 1661.1 2878.9 1488.9 2925 1425 curveto - 2939.6 1404.8 2979.8 1364.6 3000 1350 curveto - 3032.0 1327.0 3113.7 1288.5 3150 1275 curveto - 3200.3 1256.4 3275.3 1237.7 3450 1200 curveto - gs col-1 s gr - gr - -% arrowhead -n 3300 1202 m 3423 1205 l 3313 1261 l 3306 1231 l 3300 1202 l cp gs 0.00 setgray ef gr col-1 s -/Times-Roman ff 180.00 scf sf -3975 4650 m -gs 1 -1 sc (next_free) col-1 sh gr -/Times-Roman ff 180.00 scf sf -4050 4875 m -gs 1 -1 sc (magic) col-1 sh gr -/Times-Bold ff 210.00 scf sf -6825 3975 m -gs 1 -1 sc (= allocated memory) col-1 sh gr -/Helvetica-Bold ff 180.00 scf sf -3675 1125 m -gs 1 -1 sc (AllocatedBlock) col-1 sh gr -/Helvetica-Bold ff 180.00 scf sf -1575 1125 m -gs 1 -1 sc (FixItem) col-1 sh gr -/Helvetica-Bold ff 180.00 scf sf -2400 4650 m -gs 1 -1 sc (FreeHeader) col-1 sh gr -/Times-Bold ff 180.00 scf sf -5250 3600 m -gs 1 -1 sc 270.0 rot (item_size) col-1 sh gr -/Times-Bold ff 270.00 scf sf -300 525 m -gs 1 -1 sc (fix_array) col-1 sh gr -$F2psEnd -rs -end diff --git a/erts/doc/src/erl_nif.xml b/erts/doc/src/erl_nif.xml index 864b91946a..7ac8181d47 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> @@ -330,6 +330,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> diff --git a/erts/doc/src/erl_prim_loader.xml b/erts/doc/src/erl_prim_loader.xml index 9f5b3f385b..6751deda4d 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> diff --git a/erts/doc/src/erlang.xml b/erts/doc/src/erlang.xml index 06fefa8efb..711473afd2 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> @@ -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> @@ -2467,7 +2592,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 +2738,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,25 +2814,6 @@ 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 @@ -2762,11 +2889,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 +2917,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 +2932,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> @@ -3032,7 +3137,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 +3149,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 +3159,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 +3204,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 +3251,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 +3322,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 +3371,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 +3407,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 +3430,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 +3446,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 +3462,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 +3478,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 +3497,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 +3515,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 +3531,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 +3547,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 +3566,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 +3586,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 +3613,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 +3629,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> @@ -4477,6 +4686,7 @@ true</pre> </func> <func> <name name="spawn_opt" arity="2"/> + <type name="priority_level" /> <fsummary>Create a new process with a fun as entry point</fsummary> <desc> <p>Returns the pid of a new process started by the application @@ -4490,6 +4700,7 @@ true</pre> </func> <func> <name name="spawn_opt" arity="3"/> + <type name="priority_level" /> <fsummary>Create a new process with a fun as entry point on a given node</fsummary> <desc> <p>Returns the pid of a new process started by the application @@ -4501,6 +4712,7 @@ true</pre> </func> <func> <name name="spawn_opt" arity="4"/> + <type name="priority_level" /> <fsummary>Create a new process with a function as entry point</fsummary> <desc> <p>Works exactly like @@ -4602,6 +4814,7 @@ true</pre> </func> <func> <name name="spawn_opt" arity="5"/> + <type name="priority_level" /> <fsummary>Create a new process with a function as entry point on a given node</fsummary> <desc> <p>Returns the pid of a new process started by the application @@ -4723,8 +4936,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> @@ -5312,7 +5525,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> @@ -5496,6 +5713,9 @@ 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"/> <fsummary>Information about the system</fsummary> <desc> <p>Returns various information about the current system @@ -5572,6 +5792,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 @@ -5618,12 +5845,14 @@ 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><c>ets_limit</c></tag> <item> - <p>Returns the value of the distribution buffer busy limit - in bytes. This limit can be set on startup by passing the - <seealso marker="erts:erl#+zdbbl">+zdbbl</seealso> command line - flag to <c>erl</c>.</p> + <p>Returns the 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> @@ -6054,6 +6283,49 @@ ok notice. </p> </item> + <tag><c>{long_schedule, Time}</c></tag> + <item> + <p>If a process or port in the system runs uninterrupted + for at least <c>Time</c> wall clock milliseconds, a + message <c>{monitor, PidOrPort, long_schedule, Info}</c> + is sent to <c>MonitorPid</c>. <c>PidOrPort</c> is the + process or port that was running and <c>Info</c> is a + list of two-element tuples describing the event. In case + of a <c>pid()</c>, the tuples <c>{timeout, Millis}</c>, + <c>{in, Location}</c> and <c>{out, Location}</c> will be + present, where <c>Location</c> is either an MFA + (<c>{Module, Function, Arity}</c>) describing the + function where the process was scheduled in/out, or the + atom <c>undefined</c>. In case of a <c>port()</c>, the + tuples <c>{timeout, Millis}</c> and <c>{port_op,Op}</c> + will be present. <c>Op</c> will be one of <c>proc_sig</c>, + <c>timeout</c>, <c>input</c>, <c>output</c>, + <c>event</c> or <c>dist_cmd</c>, depending on which + driver callback was executing. <c>proc_sig</c> is an + internal operation and should never appear, while the + others represent the corresponding driver callbacks + <c>timeout</c>, <c>ready_input</c>, <c>ready_output</c>, + <c>event</c> and finally <c>outputv</c> (when the port + is used by distribution). The <c>Millis</c> value in + the <c>timeout</c> tuple will tell you the actual + uninterrupted execution time of the process or port, + which will always be <c>>=</c> the <c>Time</c> value + supplied when starting the trace. New tuples may be + added to the <c>Info</c> list in the future, and the + order of the tuples in the list may be changed at any + time without prior notice. + </p> + <p>This can be used to detect problems with NIF's or + drivers that take too long to execute. Generally, 1 ms + is considered a good maximum time for a driver callback + or a NIF. However, a time sharing system should usually + consider everything below 100 ms as "possible" and + fairly "normal". Schedule times above that might however + indicate swapping or a NIF/driver that is + misbehaving. Misbehaving NIF's and drivers could cause + bad resource utilization and bad overall performance of + the system.</p> + </item> <tag><c>{large_heap, Size}</c></tag> <item> <p>If a garbage collection in the system results in 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 c73cdfd290..fffa9f594c 100644 --- a/erts/doc/src/erts_alloc.xml +++ b/erts/doc/src/erts_alloc.xml @@ -1,4 +1,4 @@ -<?xml version="1.0" encoding="latin1" ?> +<?xml version="1.0" encoding="utf-8" ?> <!DOCTYPE cref SYSTEM "cref.dtd"> <cref> @@ -75,10 +75,6 @@ segments are allocated, cached segments are used if possible instead of creating new segments. This in order to reduce the number of system calls made.</item> - <tag><c>sbmbc_alloc</c></tag> - <item>Allocator used by other allocators for allocation of carriers - where only small blocks are placed. Currently this allocator is - disabled by default.</item> </taglist> <p><c>sys_alloc</c> is always enabled and cannot be disabled. <c>mseg_alloc</c> is always enabled if it is @@ -86,9 +82,7 @@ allocators can be <seealso marker="#M_e">enabled or disabled</seealso>. By default all allocators are enabled. When an allocator is disabled, <c>sys_alloc</c> is used instead of - the disabled allocator. <c>sbmbc_alloc</c> is an exception. If - <c>sbmbc_alloc</c> is disabled, other allocators will not handle - small blocks in separate carriers.</p> + the disabled allocator.</p> <p>The main idea with the <c>erts_alloc</c> library is to separate memory blocks that are used differently into different memory areas, and by this achieving less memory fragmentation. By @@ -106,20 +100,15 @@ following does <em>not</em> apply to them.</p> <p>An allocator manages multiple areas, called carriers, in which memory blocks are placed. A carrier is either placed in a - separate memory segment (allocated via <c>mseg_alloc</c>), in - the heap segment (allocated via <c>sys_alloc</c>), or inside - another carrier (in case it is a carrier created by - <c>sbmbc_alloc</c>). Multiblock + separate memory segment (allocated via <c>mseg_alloc</c>), or in + the heap segment (allocated via <c>sys_alloc</c>). Multiblock carriers are used for storage of several blocks. Singleblock carriers are used for storage of one block. Blocks that are larger than the value of the singleblock carrier threshold (<seealso marker="#M_sbct">sbct</seealso>) parameter are placed in singleblock carriers. Blocks that are smaller than the value of the <c>sbct</c> parameter are placed in multiblock - carriers. Blocks that are smaller than the small block multiblock - carrier threshold (<seealso marker="#M_sbmbct">sbmbct</seealso>) - will be placed in multiblock carriers only used for small blocks. - Normally an allocator creates a "main multiblock + carriers. Normally an allocator creates a "main multiblock carrier". Main multiblock carriers are never deallocated. The size of the main multiblock carrier is determined by the value of the <seealso marker="#M_mmbcs">mmbcs</seealso> parameter.</p> @@ -140,9 +129,7 @@ <c>sbct</c> parameter should be larger than the value of the <c>lmbcs</c> parameter, the allocator may have to create multiblock carriers that are larger than the value of the - <c>lmbcs</c> parameter, though. The size of multiblock carriers - for small blocks is determined by the small block multiblock - carrier size (<seealso marker="#M_sbmbcs">sbmbcs</seealso>). + <c>lmbcs</c> parameter, though. Singleblock carriers allocated via <c>mseg_alloc</c> are sized to whole pages.</p> <p>Sizes of carriers allocated via <c>sys_alloc</c> are @@ -183,6 +170,24 @@ 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 + can satisfy the requested block size, then find a block within + that carrier using the "adress order best fit" strategy.</p> + <p>Implementation: Balanced binary search trees are + used. The time complexity is proportional to log N, where + N is the number of free blocks.</p> + </item> <tag>Good fit</tag> <item> <p>Strategy: Try to find the best fit, but settle for the best fit @@ -219,11 +224,6 @@ but can only satisfy a limited amount of requests.</p> </section> - <note><p> - Currently only allocators using the best fit and the address order - best fit strategies are able to use "small block multi block carriers". - </p></note> - <section> <marker id="flags"></marker> <title>System Flags Effecting erts_alloc</title> @@ -245,7 +245,6 @@ the currently present allocators:</p> <list type="bulleted"> <item><c>B: binary_alloc</c></item> - <item><c>C: sbmbc_alloc</c></item> <item><c>D: std_alloc</c></item> <item><c>E: ets_alloc</c></item> <item><c>F: fix_alloc</c></item> @@ -272,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 @@ -319,10 +389,43 @@ subsystem identifier, only the specific allocator identified will be effected:</p> <taglist> - <tag><marker id="M_as"><c><![CDATA[+M<S>as bf|aobf|aoff|gf|af]]></c></marker></tag> + <tag><marker id="M_acul"><c><![CDATA[+M<S>acul <utilization>|de]]></c></marker></tag> + <item> + Abandon carrier utilization limit. A valid + <c><![CDATA[<utilization>]]></c> is an integer in the range + <c>[0, 100]</c> representing utilization in percent. When a + utilization value larger than zero is used, allocator instances + are allowed to abandon multiblock carriers. Currently the default + is zero. If <c>de</c> (default enabled) is passed instead of a + <c><![CDATA[<utilization>]]></c>, a recomended non zero utilization + value will be used. The actual value chosen depend on allocator + type and may be changed between ERTS versions. Carriers will be + abandoned when memory utilization in the allocator instance falls + below the utilization value used. Once a carrier has been abandoned, + no new allocations will be made in it. When an allocator instance + gets an increased multiblock carrier need, it will first try to + fetch an abandoned carrier from an allocator instances of the same + 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 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>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|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> <tag><marker id="M_asbcst"><c><![CDATA[+M<S>asbcst <size>]]></c></marker></tag> @@ -416,20 +519,6 @@ smaller than this threshold will be placed in multiblock carriers. On 32-bit Unix style OS this threshold can not be set higher than 8 megabytes.</item> - <tag><marker id="M_sbmbcs"><c><![CDATA[+M<S>sbmbcs <size>]]></c></marker></tag> - <item> - Small block multiblock carrier size (in bytes). Memory blocks smaller - than the small block multiblock carrier threshold - (<seealso marker="#M_sbmbct">sbmbct</seealso>) will be placed in - multiblock carriers used for small blocks only. This parameter - determines the size of such carriers. - </item> - <tag><marker id="M_sbmbct"><c><![CDATA[+M<S>sbmbct <size>]]></c></marker></tag> - <item> - Small block multiblock carrier threshold (in bytes). Memory blocks - smaller than this threshold will be placed in multiblock carriers - used for small blocks only. - </item> <tag><marker id="M_smbcs"><c><![CDATA[+M<S>smbcs <size>]]></c></marker></tag> <item> Smallest (<c>mseg_alloc</c>) multiblock carrier size (in @@ -472,6 +561,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> @@ -527,6 +621,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 66e904f64f..180447cac4 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>2011</year> + <year>2007</year><year>2013</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -85,6 +85,11 @@ $ <input>escript factorial 5</input> </pre> enter the major mode for editing Erlang source files. If the directive is present it must be located on the second line.</p> + + <p>If there is a comment selecting the <seealso + marker="stdlib:epp#encoding">encoding</seealso> it can be + located on the second line.</p> + <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> @@ -133,7 +138,9 @@ halt(1).</pre> <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.</p> + <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> <p>The script will be checked for syntactic and semantic correctness before being run. If there are warnings (such as 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 7fc61517a8..8c008c493e 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,956 @@ </header> <p>This document describes the changes made to the ERTS application.</p> +<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> + <list> + <item> + <p> + A bug in prim_inet has been corrected. If the port owner + was killed at a bad time while closing the socket port + the port could become orphaned hence causing port and + socket leaking. Reported by Fred Herbert, Dmitry Belyaev + and others.</p> + <p> + Own Id: OTP-10497 Aux Id: OTP-10562 </p> + </item> + <item> + <p> + Compilation fixes for NetBSD. Thanks to YAMAMOTO Takashi.</p> + <p> + Own Id: OTP-10941</p> + </item> + <item> + <p> + Fixed a race condition when using delayed_write when + writing to a file which would cause the same data to be + written multiple times.</p> + <p> + Own Id: OTP-10984</p> + </item> + <item> + <p> + Fix small memory leak from tracing with option + <c>meta</c>.</p> + <p> + Own Id: OTP-10997</p> + </item> + <item> + <p> + Correct typo in erlsrv usage. Thanks to Bryan Hunter</p> + <p> + Own Id: OTP-11002</p> + </item> + <item> + <p> + ct_run: delete unused function. Thanks to Tuncer Ayaz.</p> + <p> + Own Id: OTP-11003</p> + </item> + <item> + <p> + Corrections to run_erl/to_erl handshake behaviour.</p> + <p> + Own Id: OTP-11012</p> + </item> + <item> + <p> + Fix typo in type: erlang:process_info_item(). Thanks to + Andrew Tunnell-Jones.</p> + <p> + Own Id: OTP-11024</p> + </item> + <item> + <p> + Fix src/dest overlap issue in ttsl driver. Thanks to + Steve Vinoski.</p> + <p> + Own Id: OTP-11064</p> + </item> + <item> + <p> + When sending to a port using <c>erlang:send(Port, Msg, + [nosuspend])</c>, the send operation was performed + synchronously. This bug has now been fixed.</p> + <p> + Own Id: OTP-11076 Aux Id: OTP-10336 </p> + </item> + <item> + <p> + When converting a faulty binary to a list with + unicode:characters_to_list, the error return value could + contain a faulty "rest", i.e. the io_list of characters + that could not be converted was wrong. This happened only + if input was a sub binary and conversion was from utf8. + This is now corrected.</p> + <p> + Own Id: OTP-11080</p> + </item> + <item> + <p> + Runtime system could crash when reporting stale + <c>driver_select()</c>.</p> + <p> + Own Id: OTP-11084</p> + </item> + <item> + <p> + Fix lock order violation for memory instrumentation + (+Mim, +Mis, +Mit).</p> + <p> + Own Id: OTP-11085</p> + </item> + <item> + <p> + Fixed some compilation warnings on miscellaneous + platforms. Thanks to Anthony Ramine.</p> + <p> + Own Id: OTP-11086</p> + </item> + <item> + <p> + Fixed issue when flushing i/o during shutdown on windows + where the Erlang VM would sometime hang due to a race + condition.</p> + <p> + Own Id: OTP-11096</p> + </item> + <item> + <p> + Fixed issue where repeated calls to erlang:nodes() could + cause unnecessary contention in the dist_table lock.</p> + <p> + Own Id: OTP-11097</p> + </item> + <item> + <p> + Properly guard WIDE_TAG use with HAVE_WCWIDTH in + ttsl_drv. Thanks to Anthony Ramine</p> + <p> + Own Id: OTP-11106</p> + </item> + <item> + <p> + Fix some Makefile rules that didn't support silent rules. + Thanks to Anthony Ramine.</p> + <p> + Own Id: OTP-11111</p> + </item> + <item> + <p> + Fix receive support in erl_eval with a BEAM module. + Thanks to Anthony Ramine.</p> + <p> + Own Id: OTP-11137</p> + </item> + <item> + <p> + erlang:now() could suddenly jump ~24 days into the future + on Windows. This is now corrected. Thanks to Garret Smith + for reporting and testing fixes.</p> + <p> + Own Id: OTP-11146</p> + </item> + <item> + <p> + erlang:term_to_binary 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 + term_to_binary is used. </p> + <p> + Impact: Programs running term_to_binary on large terms + will run more smothly, but rescheduling will impact the + single process performance of the BIF. Single threaded + benchmarks will show degraded performance of the BIF when + called with very large terms, while general system + behaviour will be improved. The overhead for allowing + restart and reduction counting also degrades local + performance of the BIF with between 5% and 10% even for + small terms.</p> + <p> + Own Id: OTP-11163</p> + </item> + </list> + </section> + + + <section><title>Improvements and New Features</title> + <list> + <item> + <p> + Replaced the lock protecting gathering of garbage + collection statistics with a lock-free solution.</p> + <p> + Own Id: OTP-10271 Aux Id: kunagi-108 + [04c5410f-9cc4-4696-8639-36bf98686c7a-7] </p> + </item> + <item> + <p>Support for migration of memory carriers between + memory allocator instances has been introduced.</p> + <p>By default this feature is not enabled and do not + effect the characteristics of the system. When enabled it + has the following impact on the characteristics of the + system:</p> <list> <item>Reduced memory footprint when + the memory load is unevenly distributed between scheduler + specific allocator instances.</item> <item>Depending on + the default allocaton strategy used on a specific + allocator there might or might not be a slight + performance loss.</item> <item>When enabled on the + <c>fix_alloc</c> allocator, a different strategy for + management of fix blocks will be used.</item> <item>The + information returned from <seealso + marker="erlang:system_info_allocator_tuple"><c>erlang:system_info({allocator, + A})</c></seealso>, and <seealso + marker="erlang:system_info_allocator_sizes"><c>erlang:system_info({allocator_sizes, + A})</c></seealso> will be slightly different when this + feature has been enabled. An <c>mbcs_pool</c> tuple will + be present giving information about abandoned carriers, + and in the <c>fix_alloc</c> case no <c>fix_types</c> + tuple will be present. </item></list> + <p>For more information, see the documentation of the + <seealso + marker="erts_alloc#M_acul"><c>+M<S>acul</c></seealso> + command line argument.</p> + <p> + Own Id: OTP-10279</p> + </item> + <item> + <p> + Change specs for spawn_opt to use the process_level() + type declaration instead of re-defining it in various + places. Thanks to Kostis Sagonas.</p> + <p> + Own Id: OTP-11008</p> + </item> + <item> + <p> Postscript files no longer needed for the generation + of PDF files have been removed. </p> + <p> + Own Id: OTP-11016</p> + </item> + <item> + <p>Erlang source files with non-ASCII characters are now + encoded in UTF-8 (instead of latin1).</p> + <p> + Own Id: OTP-11041 Aux Id: OTP-10907 </p> + </item> + <item> + <p> + Optimization of simultaneous <c>inet_db</c> operations on + the same socket by using a lock free implementation.</p> + <p> + Impact on the characteristics of the system: Improved + performance.</p> + <p> + Own Id: OTP-11074</p> + </item> + <item> + <p> + The <c>high_msgq_watermark</c> and + <c>low_msgq_watermark</c> <c>inet</c> socket options + introduced in OTP-R16A could only be set on TCP sockets. + These options are now generic and can be set on all types + of sockets.</p> + <p> + Own Id: OTP-11075 Aux Id: OTP-10336 </p> + </item> + <item> + <p>A new better algorithm for management of the process, + and port tables has been introduced.</p> + <p>Impact on the characteristics of the system:</p> + <list> <item>The new algorithm ensures that both insert + and delete operations can be made in O(1) time + complexity. Previously used algorithm either caused + insert or delete to be O(N).</item> <item>The new + algorithm will also ensure that reuse of identifiers will + be less frequent than when the old algorithm was + used.</item> <item>Previously used algorithm ensured that + the latest created identifier compared as the largest + when comparing two identifiers of the same type that had + been created on the same node as long as no identifiers + had been reused. Since identifiers can be reused quite + fast, one has never been able to rely on this property. + Due to the introduction of this new algorithm this + property will not hold even if no identifiers has been + reused yet. This could be considered as an + incompatibility.</item> </list> + <p>Due to the above mensioned potential incompatibility, + it will still be possible to enable the old algorithm for + some time. The command line argument <seealso + marker="erl#+P"><c>+P legacy</c></seealso> will enable + the old algorithm on the process table, and <seealso + marker="erl#+Q"><c>+Q legacy</c></seealso> will do the + same for the port table. These command line arguments are + however deprecated as of their introduction and have been + scheduled for removal in OTP-R18.</p> + <p> + *** POTENTIAL INCOMPATIBILITY ***</p> + <p> + Own Id: OTP-11077</p> + </item> + <item> + <p> + Support wide characters in the shell through wcwidth(). + Thanks to Anthony Ramine. Reported by Loïc Hoguin.</p> + <p> + Own Id: OTP-11088</p> + </item> + <item> + <p> + Added total used memory for each process in erlang crash + dumps.</p> + <p> + Own Id: OTP-11098</p> + </item> + <item> + <p> + Added support for hipe on Raspberry Pi (armv6l). Thanks + to Klaus Alfert.</p> + <p> + Own Id: OTP-11125</p> + </item> + <item> + <p> + Remove 'query' from the list of reserved words in docs. + Thanks to Matthias Endler and Loïc Hoguin.</p> + <p> + Own Id: OTP-11158</p> + </item> + <item> + <p> + Lift static limitation (FD_SETSIZE) for file descriptors + on Mac OS X. (Thanks to Anthony Ramine)</p> + <p> + Own Id: OTP-11159</p> + </item> + </list> + </section> + + + <section><title>Known Bugs and Problems</title> + <list> + <item> + <p>Miscellaneous native code in OTP misbehave either due + to lengthy execution, or due to not bumping reductions + properly. Problems typically occur when passing huge sets + of data to a misbehaving BIF. Fixing this has high + priority and is being worked on, but there will remain + issues like this for some time.</p> + <p>In order to alleviate problems with scheduling which + might occur when executing misbehaving native code, the + command line argument <seealso + marker="erl#+sfwi">+sfwi</seealso> has been + introduced.</p> + <p>By default this feature is disabled and you are + advised not to enable it if you do not encounter problems + with misbehaving native code.</p> + <p>When enabled it has the following impact on the + characteristics of the system:</p> <list> <item>Work will + always be distributed between schedulers even when + executing misbehaving native code.</item> <item>It may + cause an increased amount of processes and/or ports + bouncing between schedulers which in turn will cause a + performance loss.</item> <item>It may cause reduced + performance due to reduced or lost work compaction when + all schedulers do not execute under full load.</item> + <item>An increased contention on run queue locks.</item> + </list> + <p> + Own Id: OTP-11164</p> + </item> + </list> + </section> + +</section> + +<section><title>Erts 5.10.1.2</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> + A bug in the implementation of offline schedulers has + been fixed. The bug was introduced in OTP-R16A/ERTS-5.10, + and caused work-stealing between schedulers to fail. This + in turn, caused work to accumulate in some run-queues. + The bug was only triggered when there were offline + schedulers in the system, i.e., when the amount of online + schedulers was less than the total amount of schedulers. + The effect of the bug got more severe the larger amount + of offline schedulers the system had.</p> + <p> + Own Id: OTP-11022 Aux Id: OTP-9892 </p> + </item> + </list> + </section> + +</section> + +<section><title>Erts 5.10.1.1</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> + The BIF <seealso + marker="erlang#is_process_alive/1"><c>is_process_alive/1</c></seealso> + could prematurely return <c>false</c> while the process + being inspected was terminating. This bug was introduced + in ERTS-5.10.</p> + <p> + Own Id: OTP-10926</p> + </item> + <item> + <p>Fix a problem in <c>erlang:delete_element/2</c> where + the call could corrupt one word of stack if the heap and + stack met during call.</p> + <p> + Own Id: OTP-10932</p> + </item> + <item> + <p> + The <seealso + marker="erl#+sws"><c>+sws<value></c></seealso> and + <seealso + marker="erl#+swt"><c>+swt<value></c></seealso> + system flags failed if no white space were passed between + the parameter and value parts of the flags. Upon failure, + the runtime system refused to start.</p> + <p> + Own Id: OTP-11000</p> + </item> + </list> + </section> + + + <section><title>Improvements and New Features</title> + <list> + <item> + <p> + Scheduler threads will now by default be less eager + requesting wakeup due to certain cleanup operations. This + can also be controlled using the <seealso + marker="erl#+swct"><c>+swct</c></seealso> command line + argument of <seealso + marker="erl"><c>erl(1)</c></seealso>.</p> + <p> + Own Id: OTP-10994</p> + </item> + </list> + </section> + +</section> + <section><title>Erts 5.10.1</title> <section><title>Fixed Bugs and Malfunctions</title> @@ -1520,7 +2470,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> @@ -1784,7 +2734,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> @@ -2233,7 +3183,7 @@ <item> <p> Fix typos in the epmd documentation (Thanks to Holger - Wei� )</p> + Weiß )</p> <p> Own Id: OTP-9387</p> </item> @@ -2338,7 +3288,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> @@ -2366,7 +3316,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> @@ -2510,7 +3460,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> @@ -2620,7 +3570,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> @@ -2655,7 +3605,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> @@ -3041,7 +3991,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> @@ -4547,7 +5497,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> @@ -6917,7 +7867,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..684f7b1ddd 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> 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..d52cc7f3e2 --- /dev/null +++ b/erts/doc/src/time_correction.xml @@ -0,0 +1,274 @@ +<?xml version="1.0" encoding="utf8" ?> +<!DOCTYPE chapter SYSTEM "chapter.dtd"> + +<chapter> + <header> + <copyright> + <year>1999</year><year>2013</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..afc597b729 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> |