diff options
Diffstat (limited to 'erts/doc')
| -rw-r--r-- | erts/doc/src/driver.xml | 7 | ||||
| -rw-r--r-- | erts/doc/src/driver_entry.xml | 6 | ||||
| -rw-r--r-- | erts/doc/src/epmd.xml | 252 | ||||
| -rw-r--r-- | erts/doc/src/erl.xml | 49 | ||||
| -rw-r--r-- | erts/doc/src/erl_nif.xml | 44 | ||||
| -rw-r--r-- | erts/doc/src/erlang.xml | 275 | ||||
| -rw-r--r-- | erts/doc/src/notes.xml | 522 |
7 files changed, 964 insertions, 191 deletions
diff --git a/erts/doc/src/driver.xml b/erts/doc/src/driver.xml index 006a6160de..db455312ec 100644 --- a/erts/doc/src/driver.xml +++ b/erts/doc/src/driver.xml @@ -196,11 +196,14 @@ static ErlDrvData start(ErlDrvPort port, char *command) <p>We call disconnect to log out from the database. (This should have been done from Erlang, but just in case.)</p> <code type="none"><![CDATA[ - static int do_disconnect(our_data_t* data, ei_x_buff* x); +static int do_disconnect(our_data_t* data, ei_x_buff* x); static void stop(ErlDrvData drv_data) { - do_disconnect((our_data_t*)drv_data, NULL); + our_data_t* data = (our_data_t*)drv_data; + + do_disconnect(data, NULL); + driver_free(data); } ]]></code> <p>We use the binary format only to return data to the emulator; diff --git a/erts/doc/src/driver_entry.xml b/erts/doc/src/driver_entry.xml index e71b48bd92..dd949d4048 100644 --- a/erts/doc/src/driver_entry.xml +++ b/erts/doc/src/driver_entry.xml @@ -172,7 +172,7 @@ typedef struct erl_drv_entry { added to the driver list.) The driver should return 0, or if the driver can't initialize, -1.</p> </item> - <tag><marker id="start"/>int (*start)(ErlDrvPort port, char* command)</tag> + <tag><marker id="start"/>ErlDrvData (*start)(ErlDrvPort port, char* command)</tag> <item> <p>This is called when the driver is instantiated, when <c>open_port/2</c> is called. The driver should return a @@ -188,7 +188,9 @@ typedef struct erl_drv_entry { <p>This is called when the port is closed, with <c>port_close/1</c> or <c>Port ! {self(), close}</c>. Note that terminating the port owner process also closes the - port.</p> + port. If <c>drv_data</c> is a pointer to memory allocated in + <c>start</c>, then <c>stop</c> is the place to deallocate that + memory.</p> </item> <tag><marker id="output"/>void (*output)(ErlDrvData drv_data, char *buf, int len)</tag> <item> diff --git a/erts/doc/src/epmd.xml b/erts/doc/src/epmd.xml index 796ab3820b..f01cf90a36 100644 --- a/erts/doc/src/epmd.xml +++ b/erts/doc/src/epmd.xml @@ -4,7 +4,7 @@ <comref> <header> <copyright> - <year>1996</year><year>2009</year> + <year>1996</year><year>2010</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -31,9 +31,23 @@ <rev>A</rev> <file>epmd.xml</file> </header> + <com>epmd</com> - <comsummary>Erlang Port Mapper Daemon </comsummary> + <comsummary> + <p>Erlang Port Mapper Daemon</p> + <taglist> + <tag><c><![CDATA[epmd [-d|-debug] [DbgExtra...] [-port No] [-daemon] [-relaxed_command_check]]]></c></tag> + <item> + <p>Starts the port mapper daemon</p> + </item> + <tag><c><![CDATA[epmd [-d|-debug] [-port No] [-names|-kill|-stop Name]]]></c></tag> + <item> + <p>Communicates with a running port mapper daemon</p> + </item> + </taglist> + </comsummary> <description> + <p>This daemon acts as a name server on all hosts involved in distributed Erlang computations. When an Erlang node starts, the node has a name and it obtains an address from the host @@ -46,48 +60,171 @@ The job of the <c><![CDATA[epmd]]></c> daemon is to keep track of which node name listens on which address. Hence, <c><![CDATA[epmd]]></c> map symbolic node names to machine addresses.</p> - <p>The daemon is started automatically by the Erlang start-up script.</p> - <p>The program <c><![CDATA[epmd]]></c> can also be used for a variety of other - purposes, for example checking the DNS (Domain Name System) - configuration of a host.</p> + + <p>The TCP/IP <c>epmd</c> daemon actually only keeps track of + the <c>Name</c> (first) part of an Erlang node name, the <c>Host</c> + part (whatever is after the <c><![CDATA[@]]></c> is implicit in the + node name where the <c>epmd</c> daemon was actually contacted, + as is the IP address where the Erlang node can be + reached. Consistent and correct TCP naming services are + therefore required for an Erlang network to function + correctly.</p> + + <taglist> + <tag>Starting the port mapper daemon</tag> + <item> + + <p>The daemon is started automatically by the <c>erl</c> + command if the node is to be distributed and there is no + running instance present. If automatically launched, + environment variables has to be used to alter the behavior of + the daemon. See the <seealso + marker="#environment_variables">Environment + variables</seealso> section below.</p> + + <p>If the -daemon argument is not given, the + <c><![CDATA[epmd]]></c> runs as a normal program with the + controlling terminal of the shell in which it is + started. Normally, it should run as a daemon.</p> + + <p>Regular start-up options are described in the + <seealso marker="#daemon_flags">Regular options</seealso> + section below.</p> + + <p>The <c>DbgExtra</c> options are described in the + <seealso marker="#debug_flags">DbgExtra options</seealso> + section below.</p> + + </item> + <tag>Communicating with a running port mapper daemon</tag> + <item> + + <p>Communicating with the running epmd daemon by means of the + <c>epmd</c> program is done primarily for debugging + purposes.</p> + + <p>The different queries are described in the <seealso + marker="#interactive_flags">Interactive options</seealso> + section below.</p> + + </item> + </taglist> </description> - <funcs> - <func> - <name>epmd [-daemon] </name> - <fsummary>Start a name server as a daemon</fsummary> - <desc> - <p>Starts a name server as a daemon. If it has no argument, the - <c><![CDATA[epmd]]></c> runs as a normal program with the controlling terminal - of the shell in which it is started. Normally, it should run as a - daemon.</p> - </desc> - </func> - <func> - <name>epmd -names</name> - <fsummary>Request the names of the registered Erlang nodes on this host</fsummary> - <desc> - <p>Requests the names of the local Erlang nodes <c><![CDATA[epmd]]></c> has - registered.</p> - </desc> - </func> - <func> - <name>epmd -kill</name> - <fsummary>Kill the <c><![CDATA[epmd]]></c>process</fsummary> - <desc> - <p>Kills the <c><![CDATA[epmd]]></c> process.</p> - </desc> - </func> - <func> - <name>epmd -help</name> - <fsummary>List options</fsummary> - <desc> - <p>Write short info about the usage including some debugging - options not listed here.</p> - </desc> - </func> - </funcs> + <section> + <marker id="daemon_flags"></marker> + <title>Regular options</title> + + <p>These options are available when starting the actual name server. The name server is normally started automatically by the <c>erl</c> command (if not already available), but it can also be started at i.e. system start-up.</p> + <taglist> + <tag><c><![CDATA[-port No]]></c></tag> + <item> + <p>Let this instance of epmd listen to another TCP port than + default 4369. This can be also be set using the + <c><![CDATA[ERL_EPMD_PORT]]></c> environment variable, see the + section <seealso marker="#environment_variables">Environment + variables</seealso> below</p> + </item> + <tag><c><![CDATA[-d | -debug]]></c></tag> + <item> + + <p>Enable debug output. The more <c>-d</c> flags given, the more + debug output you will get (to a certain limit). This option is + most useful when the epmd daemon is not started as a daemon.</p> + </item> + <tag><c><![CDATA[-daemon]]></c></tag> + <item> + <p>Start epmd detached from the controlling terminal. Logging will end up in syslog when available and correctly configured. If the epmd daemon is started at boot, this option should definitely be used. It is also used when the <c>erl</c> command automatically starts <c>epmd</c>.</p> + </item> + <tag><c><![CDATA[-relaxed_command_check]]></c></tag> + <item> + <p>Start the epmd program with relaxed command checking (mostly for backward compatibility). This affects the following:</p> + <list type="bulleted"> + <item> + <p>With relaxed command checking, the <c>epmd</c> daemon can be killed from the localhost with i.e. <c>epmd -kill</c> even if there are active nodes registered. Normally only daemons with an empty node database can be killed with the <c>epmd -kill</c> command.</p> + </item> + <item> + <p>The <c>epmd -stop</c> command (and the corresponding messages to epmd, as can be given using <c>erl_interface/ei</c>) is normally always ignored, as it opens up for strange situation when two nodes of the same name can be alive at the same time. A node unregisters itself by just closing the connection to epmd, why the <c>stop</c> command was only intended for use in debugging situations.</p> + <p>With relaxed command checking enabled, you can forcibly unregister live nodes.</p> + </item> + </list> + <p>Relaxed command checking can also be enabled by setting the environment variable <c>ERL_EPMD_RELAXED_COMMAND_CHECK</c> prior to starting <c>epmd</c>.</p> + <p>Only use relaxed command checking on systems with very limited interactive usage.</p> + </item> + </taglist> + </section> <section> + <marker id="debug_flags"></marker> + <title>DbgExtra options</title> + <p>These options are purely for debugging and testing epmd clients, they should not be used in normal operation.</p> + + <taglist> + <tag><c><![CDATA[-packet_timeout Seconds]]></c></tag> + <item> + <p>Set the number of seconds a connection can be + inactive before epmd times out and closes the + connection (default 60).</p> + </item> + <tag><c><![CDATA[-delay_accept Seconds]]></c></tag> + <item> + <p>To simulate a busy server you can insert a delay between epmd + gets notified about that a new connection is requested and + when the connections gets accepted.</p> + </item> + <tag><c><![CDATA[-delay_write Seconds]]></c></tag> + <item> + <p>Also a simulation of a busy server. Inserts + a delay before a reply is sent.</p> + </item> + </taglist> + </section> + <section> + <marker id="interactive_flags"></marker> + <title>Interactive options</title> + <p>These options make <c>epmd</c> run as an interactive command displaying the results of sending queries ta an already running instance of <c>epmd</c>. The epmd contacted is always on the local node, but the <c>-port</c> option can be used to select between instances if several are running using different port on the host.</p> + <taglist> + <tag><c><![CDATA[-port No]]></c></tag> + <item> + <p>Contacts the <c>epmd</c> listening on the given TCP port number + (default 4369). This can be also be set using the + <c><![CDATA[ERL_EPMD_PORT]]></c> environment variable, see the + section <seealso marker="#environment_variables">Environment + variables</seealso> below</p> + </item> + <tag><c><![CDATA[-names]]></c></tag> + <item> + <p>List names registered with the currently running epmd</p> + </item> + <tag><c><![CDATA[-kill]]></c></tag> + <item> + <p>Kill the currently running <c>epmd</c>.</p> + + <p>Killing the running <c>epmd</c> is only allowed if <c>epmd + -names</c> show an empty database or + <c>-relaxed_command_check</c> was given when the running + instance of <c>epmd</c> was started. Note that + <c>-relaxed_command_check</c> is given when starting the + daemon that is to accept killing when it has live nodes + registered. When running epmd interactively, + <c>-relaxed_command_check</c> has no effect. A daemon that is + started without relaxed command checking has to be killed + using i.e. signals or some other OS specific method if it has + active clients registered.</p> + </item> + <tag><c><![CDATA[-stop Name]]></c></tag> + <item> + <p>Forcibly unregister a live node from <c>epmd</c>'s database</p> + + <p>This command can only be used when contacting <c>epmd</c> + instances started with the <c>-relaxed_command_check</c> + flag. Note that relaxed command checking has to be enabled for + the <c>epmd</c> daemon contacted, When running epmd + interactively, + <c>-relaxed_command_check</c> has no effect.</p> + </item> + </taglist> + </section> + <section> <marker id="environment_variables"></marker> <title>Environment variables</title> <taglist> @@ -99,6 +236,15 @@ independent clusters of nodes, to co-exist on the same host. All nodes in a cluster must use the same epmd port number.</p> </item> + <tag><c><![CDATA[ERL_EPMD_RELAXED_COMMAND_CHECK]]></c></tag> + <item> + <p>If set prior to start, the <c>epmd</c> daemon will behave + as if the <c>-relaxed_command_check</c> option was given at + start-up. If consequently setting this option before starting + the Erlang virtual machine, the automatically started + <c>epmd</c> will accept the <c>-kill</c> and <c>-stop</c> + commands without restrictions.</p> + </item> </taglist> </section> @@ -116,5 +262,29 @@ silently be ignored. </p> </section> + <section> + <title>Access restrictions</title> + <p>The <c>epmd</c> daemon accepts messages from both localhost and + remote hosts. However, only the query commands are answered (and + acted upon) if the query comes from a remote host. It is always an + error to try to register a nodename if the client is not a process + located on the same host as the <c>epmd</c> instance is running on, + why such requests are considered hostile and the connection is + immediately closed.</p> + + <p>The queries accepted from remote nodes are:</p> + <list type="bulleted"> + <item> + <p>Port queries - i.e. on which port does the node with a given + name listen</p> + </item> + <item> + <p>Name listing - i.e. give a list of all names registered on + the host</p> + </item> + </list> + <p>To restrict access further, firewall software has to be used.</p> + </section> + </comref> diff --git a/erts/doc/src/erl.xml b/erts/doc/src/erl.xml index 0e26d62548..a1d73fb698 100644 --- a/erts/doc/src/erl.xml +++ b/erts/doc/src/erl.xml @@ -685,8 +685,8 @@ <seealso marker="erlang#system_flag_scheduler_bind_type">erlang:system_flag(scheduler_bind_type, default_bind)</seealso>. </p></item> </taglist> - <p>Binding of schedulers are currently only supported on newer - Linux and Solaris systems.</p> + <p>Binding of schedulers is currently only supported on newer + Linux, Solaris, FreeBSD, and Windows systems.</p> <p>If no CPU topology is available when the <c>+sbt</c> flag is processed and <c>BindType</c> is any other type than <c>u</c>, the runtime system will fail to start. CPU @@ -831,14 +831,28 @@ <p>For more information, see <seealso marker="erlang#system_flag_cpu_topology">erlang:system_flag(cpu_topology, CpuTopology)</seealso>.</p> </item> + <tag><marker id="+swt"><c>+swt very_low|low|medium|high|very_high</c></marker></tag> + <item> + <p>Set scheduler wakeup threshold. Default is <c>medium</c>. + The threshold determines when to wake up sleeping schedulers + when more work than can be handled by currently awake schedulers + exist. A low threshold will cause earlier wakeups, and a high + threshold will cause later wakeups. Early wakeups will + distribute work over multiple schedulers faster, but work will + more easily bounce between schedulers. + </p> + <p><em>NOTE:</em> This flag may be removed or changed at any time + without prior notice. + </p> + </item> + <tag><marker id="sched_thread_stack_size"><c><![CDATA[+sss size]]></c></marker></tag> + <item> + <p>Suggested stack size, in kilowords, for scheduler threads. + Valid range is 4-8192 kilowords. The default stack size + is OS dependent.</p> + </item> </taglist> </item> - <tag><marker id="sched_thread_stack_size"><c><![CDATA[+sss size]]></c></marker></tag> - <item> - <p>Suggested stack size, in kilowords, for scheduler threads. - Valid range is 4-8192 kilowords. The default stack size - is OS dependent.</p> - </item> <tag><marker id="+t"><c><![CDATA[+t size]]></c></marker></tag> <item> <p>Set the maximum number of atoms the VM can handle. Default is 1048576.</p> @@ -892,6 +906,25 @@ <seealso marker="kernel:error_logger#warning_map/0">error_logger(3)</seealso> for further information.</p> </item> + <tag><c><![CDATA[+zFlag Value]]></c></tag> + <item> + <p>Miscellaneous flags.</p> + <taglist> + <tag><marker id="+zdbbl"><c>+zdbbl size</c></marker></tag> + <item> + <p>Set the distribution buffer busy limit + (<seealso marker="erlang#system_info_dist_buf_busy_limit">dist_buf_busy_limit</seealso>) + in kilobytes. Valid range is 1-2097151. Default is 1024.</p> + <p>A larger buffer limit will allow processes to buffer + more outgoing messages over the distribution. When the + buffer limit has been reached, sending processes will be + suspended until the buffer size has shrunk. The buffer + limit is per distribution channel. A higher limit will + give lower latency and higher throughput at the expense + of higher memory usage.</p> + </item> + </taglist> + </item> </taglist> </section> diff --git a/erts/doc/src/erl_nif.xml b/erts/doc/src/erl_nif.xml index f7b7b2f346..27887cbdf6 100644 --- a/erts/doc/src/erl_nif.xml +++ b/erts/doc/src/erl_nif.xml @@ -4,7 +4,7 @@ <cref> <header> <copyright> - <year>2001</year><year>2009</year> + <year>2001</year><year>2010</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -34,11 +34,10 @@ <lib>erl_nif</lib> <libsummary>API functions for an Erlang NIF library</libsummary> <description> - <warning><p>The NIF concept was introduced in R13B03 as an - EXPERIMENTAL feature. The interfaces may be changed in any way - in coming releases. The plan is however to lift the experimental label and - maintain interface backward compatibility from R14B.</p> - <p>Incompatible changes in <em>R14A</em>:</p> + <note><p>The NIF concept is officially supported from R14B. NIF source code + written for earlier experimental versions might need adaption to run on R14B.</p> + <p>No incompatible changes between <em>R14B</em> and R14A.</p> + <p>Incompatible changes between <em>R14A</em> and R13B04:</p> <list> <item>Environment argument removed for <c>enif_alloc</c>, <c>enif_realloc</c>, <c>enif_free</c>, <c>enif_alloc_binary</c>, @@ -50,14 +49,14 @@ <item>Module argument added to <c>enif_open_resource_type</c> while changing name spaces of resource types from global to module local.</item> </list> - <p>Incompatible changes in <em>R13B04</em>:</p> + <p>Incompatible changes between <em>R13B04</em> and R13B03:</p> <list> <item>The function prototypes of the NIFs have changed to expect <c>argc</c> and <c>argv</c> arguments. The arity of a NIF is by that no longer limited to 3.</item> <item><c>enif_get_data</c> renamed as <c>enif_priv_data</c>.</item> <item><c>enif_make_string</c> got a third argument for character encoding.</item> </list> - </warning> + </note> <p>A NIF library contains native implementation of some functions of an Erlang module. The native implemented functions (NIFs) are @@ -456,6 +455,10 @@ typedef enum { to return information about the runtime system. Contains currently the exact same content as <seealso marker="erl_driver#ErlDrvSysInfo">ErlDrvSysInfo</seealso>.</p> </item> + <tag><marker id="ErlNifSInt64"/>ErlNifSInt64</tag> + <item><p>A native signed 64-bit integer type.</p></item> + <tag><marker id="ErlNifUInt64"/>ErlNifUInt64</tag> + <item><p>A native unsigned 64-bit integer type.</p></item> </taglist> </section> @@ -571,7 +574,13 @@ typedef enum { <fsummary>Read an integer term</fsummary> <desc><p>Set <c>*ip</c> to the integer value of <c>term</c>. Return true on success or false if <c>term</c> is not an - integer or is outside the bounds of type <c>int</c></p></desc> + integer or is outside the bounds of type <c>int</c>.</p></desc> + </func> + <func><name><ret>int</ret><nametext>enif_get_int64(ErlNifEnv* env, ERL_NIF_TERM term, ErlNifSInt64* ip)</nametext></name> + <fsummary>Read a 64-bit integer term</fsummary> + <desc><p>Set <c>*ip</c> to the integer value of + <c>term</c>. Return true on success or false if <c>term</c> is not an + integer or is outside the bounds of a signed 64-bit integer.</p></desc> </func> <func><name><ret>int</ret><nametext>enif_get_local_pid(ErlNifEnv* env, ERL_NIF_TERM term, ErlNifPid* pid)</nametext></name> <fsummary>Read an local pid term</fsummary> @@ -633,7 +642,12 @@ typedef enum { return true, or return false if <c>term</c> is not an unsigned integer or is outside the bounds of type <c>unsigned int</c>.</p></desc> </func> - + <func><name><ret>int</ret><nametext>enif_get_uint64(ErlNifEnv* env, ERL_NIF_TERM term, ErlNifUInt64* ip)</nametext></name> + <fsummary>Read an unsigned 64-bit integer term.</fsummary> + <desc><p>Set <c>*ip</c> to the unsigned integer value of <c>term</c> and + return true, or return false if <c>term</c> is not an unsigned integer or + is outside the bounds of an unsigned 64-bit integer.</p></desc> + </func> <func><name><ret>int</ret><nametext>enif_get_ulong(ErlNifEnv* env, ERL_NIF_TERM term, unsigned long* ip)</nametext></name> <fsummary>Read an unsigned integer term.</fsummary> <desc><p>Set <c>*ip</c> to the unsigned long integer value of <c>term</c> @@ -758,6 +772,10 @@ typedef enum { <fsummary>Create an integer term</fsummary> <desc><p>Create an integer term.</p></desc> </func> + <func><name><ret>ERL_NIF_TERM</ret><nametext>enif_make_int64(ErlNifEnv* env, ErlNifSInt64 i)</nametext></name> + <fsummary>Create an integer term</fsummary> + <desc><p>Create an integer term from a signed 64-bit integer.</p></desc> + </func> <func><name><ret>ERL_NIF_TERM</ret><nametext>enif_make_list(ErlNifEnv* env, unsigned cnt, ...)</nametext></name> <fsummary>Create a list term.</fsummary> <desc><p>Create an ordinary list term of length <c>cnt</c>. Expects @@ -894,6 +912,10 @@ typedef enum { <fsummary>Create an unsigned integer term</fsummary> <desc><p>Create an integer term from an <c>unsigned int</c>.</p></desc> </func> + <func><name><ret>ERL_NIF_TERM</ret><nametext>enif_make_uint64(ErlNifEnv* env, ErlNifUInt64 i)</nametext></name> + <fsummary>Create an unsigned integer term</fsummary> + <desc><p>Create an integer term from an unsigned 64-bit integer.</p></desc> + </func> <func><name><ret>ERL_NIF_TERM</ret><nametext>enif_make_ulong(ErlNifEnv* env, unsigned long i)</nametext></name> <fsummary>Create an integer term from an unsigned long int</fsummary> <desc><p>Create an integer term from an <c>unsigned long int</c>.</p></desc> @@ -1108,7 +1130,7 @@ typedef enum { </funcs> <section> <title>SEE ALSO</title> - <p><seealso marker="erlang#load_nif-2">load_nif(3)</seealso></p> + <p><seealso marker="erlang#load_nif-2">erlang:load_nif/2</seealso></p> </section> </cref> diff --git a/erts/doc/src/erlang.xml b/erts/doc/src/erlang.xml index 54a0a80536..638f7eef10 100644 --- a/erts/doc/src/erlang.xml +++ b/erts/doc/src/erlang.xml @@ -80,7 +80,7 @@ iolist() = [char() | binary() | iolist()] </desc> </func> <func> - <name>adler32(Data) -> int()</name> + <name>erlang:adler32(Data) -> int()</name> <fsummary>Compute adler32 checksum</fsummary> <type> <v>Data = iodata()</v> @@ -90,7 +90,7 @@ iolist() = [char() | binary() | iolist()] </desc> </func> <func> - <name>adler32(OldAdler, Data) -> int()</name> + <name>erlang:adler32(OldAdler, Data) -> int()</name> <fsummary>Compute adler32 checksum</fsummary> <type> <v>OldAdler = int()</v> @@ -102,17 +102,17 @@ iolist() = [char() | binary() | iolist()] <c>Data</c>.</p> <p>The following code:</p> <code> - X = adler32(Data1), - Y = adler32(X,Data2). + X = erlang:adler32(Data1), + Y = erlang:adler32(X,Data2). </code> <p>- would assign the same value to <c>Y</c> as this would:</p> <code> - Y = adler32([Data1,Data2]). + Y = erlang:adler32([Data1,Data2]). </code> </desc> </func> <func> - <name>adler32_combine(FirstAdler, SecondAdler, SecondSize) -> int()</name> + <name>erlang:adler32_combine(FirstAdler, SecondAdler, SecondSize) -> int()</name> <fsummary>Combine two adler32 checksums</fsummary> <type> <v>FirstAdler = SecondAdler = int()</v> @@ -124,14 +124,14 @@ iolist() = [char() | binary() | iolist()] the second checksum to be known.</p> <p>The following code:</p> <code> - Y = adler32(Data1), - Z = adler32(Y,Data2). + Y = erlang:adler32(Data1), + Z = erlang:adler32(Y,Data2). </code> <p>- would assign the same value to <c>Z</c> as this would:</p> <code> - X = adler32(Data1), - Y = adler32(Data2), - Z = adler32_combine(X,Y,iolist_size(Data2)). + X = erlang:adler32(Data1), + Y = erlang:adler32(Data2), + Z = erlang:adler32_combine(X,Y,iolist_size(Data2)). </code> </desc> </func> @@ -147,7 +147,7 @@ iolist() = [char() | binary() | iolist()] <c>Tuple1</c>, and contains the elements in <c>Tuple1</c> followed by <c>Term</c> as the last element. Semantically equivalent to - <c>list_to_tuple(tuple_to_list(Tuple ++ [Term])</c>, but much + <c>list_to_tuple(tuple_to_list(Tuple) ++ [Term])</c>, but much faster.</p> <pre> > <input>erlang:append_element({one, two}, three).</input> @@ -499,7 +499,7 @@ iolist() = [char() | binary() | iolist()] <name>erlang:cancel_timer(TimerRef) -> Time | false</name> <fsummary>Cancel a timer</fsummary> <type> - <v>TimerRef = ref()</v> + <v>TimerRef = reference()</v> <v>Time = int()</v> </type> <desc> @@ -553,7 +553,7 @@ false</pre> </desc> </func> <func> - <name>crc32(Data) -> int()</name> + <name>erlang:crc32(Data) -> int()</name> <fsummary>Compute crc32 (IEEE 802.3) checksum</fsummary> <type> <v>Data = iodata()</v> @@ -563,7 +563,7 @@ false</pre> </desc> </func> <func> - <name>crc32(OldCrc, Data) -> int()</name> + <name>erlang:crc32(OldCrc, Data) -> int()</name> <fsummary>Compute crc32 (IEEE 802.3) checksum</fsummary> <type> <v>OldCrc = int()</v> @@ -575,17 +575,17 @@ false</pre> <c>Data</c>.</p> <p>The following code:</p> <code> - X = crc32(Data1), - Y = crc32(X,Data2). + X = erlang:crc32(Data1), + Y = erlang:crc32(X,Data2). </code> <p>- would assign the same value to <c>Y</c> as this would:</p> <code> - Y = crc32([Data1,Data2]). + Y = erlang:crc32([Data1,Data2]). </code> </desc> </func> <func> - <name>crc32_combine(FirstCrc, SecondCrc, SecondSize) -> int()</name> + <name>erlang:crc32_combine(FirstCrc, SecondCrc, SecondSize) -> int()</name> <fsummary>Combine two crc32 (IEEE 802.3) checksums</fsummary> <type> <v>FirstCrc = SecondCrc = int()</v> @@ -597,14 +597,14 @@ false</pre> the second checksum to be known.</p> <p>The following code:</p> <code> - Y = crc32(Data1), - Z = crc32(Y,Data2). + Y = erlang:crc32(Data1), + Z = erlang:crc32(Y,Data2). </code> <p>- would assign the same value to <c>Z</c> as this would:</p> <code> - X = crc32(Data1), - Y = crc32(Data2), - Z = crc32_combine(X,Y,iolist_size(Data2)). + X = erlang:crc32(Data1), + Y = erlang:crc32(Data2), + Z = erlang:crc32_combine(X,Y,iolist_size(Data2)). </code> </desc> </func> @@ -624,7 +624,7 @@ false</pre> </desc> </func> <func> - <name>decode_packet(Type,Bin,Options) -> {ok,Packet,Rest} | {more,Length} | {error,Reason}</name> + <name>erlang:decode_packet(Type,Bin,Options) -> {ok,Packet,Rest} | {more,Length} | {error,Reason}</name> <fsummary>Extracts a protocol packet from a binary</fsummary> <type> <v>Bin = binary()</v> @@ -760,18 +760,18 @@ false</pre> </desc> </func> <func> - <name>erlang:demonitor(MonitorRef) -> true</name> + <name>demonitor(MonitorRef) -> true</name> <fsummary>Stop monitoring</fsummary> <type> - <v>MonitorRef = ref()</v> + <v>MonitorRef = reference()</v> </type> <desc> <p>If <c>MonitorRef</c> is a reference which the calling process obtained by calling - <seealso marker="#monitor/2">erlang:monitor/2</seealso>, + <seealso marker="#monitor/2">monitor/2</seealso>, this monitoring is turned off. If the monitoring is already turned off, nothing happens.</p> - <p>Once <c>erlang:demonitor(MonitorRef)</c> has returned it is + <p>Once <c>demonitor(MonitorRef)</c> has returned it is guaranteed that no <c>{'DOWN', MonitorRef, _, _, _}</c> message due to the monitor will be placed in the callers message queue in the future. A <c>{'DOWN', MonitorRef, _, _, _}</c> message @@ -779,10 +779,10 @@ false</pre> the call, though. Therefore, in most cases, it is advisable to remove such a <c>'DOWN'</c> message from the message queue after monitoring has been stopped. - <seealso marker="#demonitor/2">erlang:demonitor(MonitorRef, [flush])</seealso> can be used instead of - <c>erlang:demonitor(MonitorRef)</c> if this cleanup is wanted.</p> + <seealso marker="#demonitor/2">demonitor(MonitorRef, [flush])</seealso> can be used instead of + <c>demonitor(MonitorRef)</c> if this cleanup is wanted.</p> <note> - <p>Prior to OTP release R11B (erts version 5.5) <c>erlang:demonitor/1</c> + <p>Prior to OTP release R11B (erts version 5.5) <c>demonitor/1</c> behaved completely asynchronous, i.e., the monitor was active until the "demonitor signal" reached the monitored entity. This had one undesirable effect, though. You could never know when @@ -800,10 +800,10 @@ false</pre> </desc> </func> <func> - <name>erlang:demonitor(MonitorRef, OptionList) -> true|false</name> + <name>demonitor(MonitorRef, OptionList) -> true|false</name> <fsummary>Stop monitoring</fsummary> <type> - <v>MonitorRef = ref()</v> + <v>MonitorRef = reference()</v> <v>OptionList = [Option]</v> <v>Option = flush</v> <v>Option = info</v> @@ -812,8 +812,8 @@ false</pre> <p>The returned value is <c>true</c> unless <c>info</c> is part of <c>OptionList</c>. </p> - <p><c>erlang:demonitor(MonitorRef, [])</c> is equivalent to - <seealso marker="#demonitor/1">erlang:demonitor(MonitorRef)</seealso>.</p> + <p><c>demonitor(MonitorRef, [])</c> is equivalent to + <seealso marker="#demonitor/1">demonitor(MonitorRef)</seealso>.</p> <p>Currently the following <c>Option</c>s are valid:</p> <taglist> <tag><c>flush</c></tag> @@ -821,11 +821,11 @@ false</pre> <p>Remove (one) <c>{_, MonitorRef, _, _, _}</c> message, if there is one, from the callers message queue after monitoring has been stopped.</p> - <p>Calling <c>erlang:demonitor(MonitorRef, [flush])</c> + <p>Calling <c>demonitor(MonitorRef, [flush])</c> is equivalent to the following, but more efficient:</p> <code type="none"> - erlang:demonitor(MonitorRef), + demonitor(MonitorRef), receive {_, MonitorRef, _, _, _} -> true @@ -863,7 +863,7 @@ false</pre> </note> <p>Failure: <c>badarg</c> if <c>OptionList</c> is not a list, or if <c>Option</c> is not a valid option, or the same failure as for - <seealso marker="#demonitor/1">erlang:demonitor/1</seealso></p> + <seealso marker="#demonitor/1">demonitor/1</seealso></p> </desc> </func> <func> @@ -944,7 +944,7 @@ b</pre> </desc> </func> <func> - <name>erlang:error(Reason)</name> + <name>error(Reason)</name> <fsummary>Stop execution with a given reason</fsummary> <type> <v>Reason = term()</v> @@ -957,7 +957,7 @@ b</pre> function first). Since evaluating this function causes the process to terminate, it has no return value.</p> <pre> -> <input>catch erlang:error(foobar).</input> +> <input>catch error(foobar).</input> {'EXIT',{foobar,[{erl_eval,do_apply,5}, {erl_eval,expr,5}, {shell,exprs,6}, @@ -966,7 +966,7 @@ b</pre> </desc> </func> <func> - <name>erlang:error(Reason, Args)</name> + <name>error(Reason, Args)</name> <fsummary>Stop execution with a given reason</fsummary> <type> <v>Reason = term()</v> @@ -1483,7 +1483,7 @@ os_prompt%</pre> </desc> </func> <func> - <name>erlang:integer_to_list(Integer, Base) -> string()</name> + <name>integer_to_list(Integer, Base) -> string()</name> <fsummary>Text representation of an integer</fsummary> <type> <v>Integer = int()</v> @@ -1493,7 +1493,7 @@ os_prompt%</pre> <p>Returns a string which corresponds to the text representation of <c>Integer</c> in base <c>Base</c>.</p> <pre> -> <input>erlang:integer_to_list(1023, 16).</input> +> <input>integer_to_list(1023, 16).</input> "3FF"</pre> </desc> </func> @@ -1932,7 +1932,7 @@ os_prompt%</pre> </desc> </func> <func> - <name>erlang:list_to_integer(String, Base) -> int()</name> + <name>list_to_integer(String, Base) -> int()</name> <fsummary>Convert from text representation to an integer</fsummary> <type> <v>String = string()</v> @@ -1942,7 +1942,7 @@ os_prompt%</pre> <p>Returns an integer whose text representation in base <c>Base</c> is <c>String</c>.</p> <pre> -> <input>erlang:list_to_integer("3FF", 16).</input> +> <input>list_to_integer("3FF", 16).</input> 1023</pre> <p>Failure: <c>badarg</c> if <c>String</c> contains a bad representation of an integer.</p> @@ -2034,16 +2034,18 @@ os_prompt%</pre> <v>Text = string()</v> </type> <desc> - <warning> - <p>This BIF is still an experimental feature. The interface - may be changed in any way in future releases.</p><p>In - R13B03 the return value on failure was + <note> + <p>In releases older than OTP R14B, NIFs were an + experimental feature. Versions of OTP older than R14B might + have different and possibly incompatible NIF semantics and + interfaces. For example, in R13B03 the return value on + failure was <c>{error,Reason,Text}</c>.</p> - </warning> + </note> <p>Loads and links a dynamic library containing native implemented functions (NIFs) for a module. <c>Path</c> is a file path to the sharable object/dynamic library file minus - the OS-dependant file extension (.so for Unix and .ddl for + the OS-dependent file extension (.so for Unix and .dll for Windows). See <seealso marker="erl_nif">erl_nif</seealso> on how to implement a NIF library.</p> <p><c>LoadInfo</c> can be any term. It will be passed on to @@ -2160,7 +2162,7 @@ os_prompt%</pre> </desc> </func> <func> - <name>make_ref() -> ref()</name> + <name>make_ref() -> reference()</name> <fsummary>Return an almost unique reference</fsummary> <desc> <p>Returns an almost unique reference.</p> @@ -2486,7 +2488,7 @@ os_prompt%</pre> </desc> </func> <func> - <name>erlang:monitor(Type, Item) -> MonitorRef</name> + <name>monitor(Type, Item) -> MonitorRef</name> <fsummary>Start monitoring</fsummary> <type> <v>Type = process</v> @@ -2522,7 +2524,7 @@ os_prompt%</pre> <note> <p>When a process is monitored by registered name, the process that has the registered name at the time when - <c>erlang:monitor/2</c> is called will be monitored. + <c>monitor/2</c> is called will be monitored. The monitor will not be effected, if the registered name is unregistered.</p> </note> @@ -2556,20 +2558,20 @@ os_prompt%</pre> </item> </taglist> <note> - <p>If/when <c>erlang:monitor/2</c> is extended (e.g. to + <p>If/when <c>monitor/2</c> is extended (e.g. to handle other item types than <c>process</c>), other possible values for <c>Object</c>, and <c>Info</c> in the <c>'DOWN'</c> message will be introduced.</p> </note> <p>The monitoring is turned off either when the <c>'DOWN'</c> message is sent, or when - <seealso marker="#demonitor/1">erlang:demonitor/1</seealso> + <seealso marker="#demonitor/1">demonitor/1</seealso> is called.</p> <p>If an attempt is made to monitor a process on an older node (where remote process monitoring is not implemented or one where remote process monitoring by registered name is not implemented), the call fails with <c>badarg</c>.</p> - <p>Making several calls to <c>erlang:monitor/2</c> for the same + <p>Making several calls to <c>monitor/2</c> for the same <c>Item</c> is not an error; it results in as many, completely independent, monitorings.</p> <note> @@ -2690,7 +2692,7 @@ os_prompt%</pre> <name>node(Arg) -> Node</name> <fsummary>At which node is a pid, port or reference located</fsummary> <type> - <v>Arg = pid() | port() | ref()</v> + <v>Arg = pid() | port() | reference()</v> <v>Node = node()</v> </type> <desc> @@ -3897,11 +3899,11 @@ os_prompt%</pre> <tag><c>{monitored_by, Pids}</c></tag> <item> <p>A list of pids that are monitoring the process (with - <c>erlang:monitor/2</c>).</p> + <c>monitor/2</c>).</p> </item> <tag><c>{monitors, Monitors}</c></tag> <item> - <p>A list of monitors (started by <c>erlang:monitor/2</c>) + <p>A list of monitors (started by <c>monitor/2</c>) that are active for the process. For a local process monitor or a remote process monitor by pid, the list item is <c>{process, Pid}</c>, and for a remote process @@ -4090,7 +4092,7 @@ os_prompt%</pre> terminate, it has no return value - unless the arguments are invalid, in which case the function <em>returns the error reason</em>, that is <c>badarg</c>. If you want to be really sure not to return you can call - <c>erlang:error(erlang:raise(Class, Reason, Stacktrace))</c> + <c>error(erlang:raise(Class, Reason, Stacktrace))</c> and hope to distinguish exceptions later.</p> </desc> </func> @@ -4098,7 +4100,7 @@ os_prompt%</pre> <name>erlang:read_timer(TimerRef) -> int() | false</name> <fsummary>Number of milliseconds remaining for a timer</fsummary> <type> - <v>TimerRef = ref()</v> + <v>TimerRef = reference()</v> </type> <desc> <p><c>TimerRef</c> is a timer reference returned by @@ -4121,7 +4123,7 @@ os_prompt%</pre> <name>erlang:ref_to_list(Ref) -> string()</name> <fsummary>Text representation of a reference</fsummary> <type> - <v>Ref = ref()</v> + <v>Ref = reference()</v> </type> <desc> <p>Returns a string which corresponds to the text @@ -4300,7 +4302,7 @@ true</pre> <v>Dest = pid() | RegName </v> <v> LocalPid = pid() (of a process, alive or dead, on the local node)</v> <v>Msg = term()</v> - <v>TimerRef = ref()</v> + <v>TimerRef = reference()</v> </type> <desc> <p>Starts a timer which will send the message <c>Msg</c> @@ -4513,7 +4515,7 @@ true</pre> </desc> </func> <func> - <name>spawn(Node, Module, Function, ArgumentList) -> pid()</name> + <name>spawn(Node, Module, Function, Args) -> pid()</name> <fsummary>Create a new process with a function as entry point on a given node</fsummary> <type> <v>Node = node()</v> @@ -4691,7 +4693,7 @@ true</pre> <tag><c>monitor</c></tag> <item> <p>Monitor the new process (just like - <seealso marker="#monitor/2">erlang:monitor/2</seealso> does).</p> + <seealso marker="#monitor/2">monitor/2</seealso> does).</p> </item> <tag><c>{priority, Level}</c></tag> <item> @@ -4829,7 +4831,7 @@ true</pre> <v> LocalPid = pid() (of a process, alive or dead, on the local node)</v> <v> RegName = atom()</v> <v>Msg = term()</v> - <v>TimerRef = ref()</v> + <v>TimerRef = reference()</v> </type> <desc> <p>Starts a timer which will send the message @@ -5175,9 +5177,9 @@ true</pre> schedulers actually have bound as requested, call <seealso marker="#system_info_scheduler_bindings">erlang:system_info(scheduler_bindings)</seealso>. </p> - <p>Schedulers can currently only be bound on newer Linux - and Solaris systems, but more systems will be supported - in the future. + <p>Schedulers can currently only be bound on newer Linux, + Solaris, FreeBSD, and Windows systems, but more systems will be + supported in the future. </p> <p>In order for the runtime system to be able to bind schedulers, the CPU topology needs to be known. If the runtime system fails @@ -5364,7 +5366,7 @@ true</pre> <p>Returns <c>{Allocator, Version, Features, Settings}.</c></p> <p>Types:</p> <list type="bulleted"> - <item><c>Allocator = undefined | elib_malloc | glibc</c></item> + <item><c>Allocator = undefined | glibc</c></item> <item><c>Version = [int()]</c></item> <item><c>Features = [atom()]</c></item> <item><c>Settings = [{Subsystem, [{Parameter, Value}]}]</c></item> @@ -5379,7 +5381,7 @@ true</pre> implementation used. If <c>Allocator</c> equals <c>undefined</c>, the <c>malloc()</c> implementation used could not be identified. Currently - <c>elib_malloc</c> and <c>glibc</c> can be identified.</p> + <c>glibc</c> can be identified.</p> </item> <item> <p><c>Version</c> is a list of integers (but not a @@ -5456,6 +5458,16 @@ true</pre> <seealso marker="#system_info_allocator_tuple">erlang:system_info({allocator, Alloc})</seealso>. </p> </item> + <tag><c>build_type</c></tag> + <item> + <p>Returns an atom describing the build type of the runtime + system. This is normally the atom <c>opt</c> for optimized. + Other possible return values are <c>debug</c>, <c>purify</c>, + <c>quantify</c>, <c>purecov</c>, <c>gcov</c>, <c>valgrind</c>, + <c>gprof</c>, and <c>lcnt</c>. Possible return values + may be added and/or removed at any time without prior notice. + </p> + </item> <tag><c>c_compiler_used</c></tag> <item> <p>Returns a two-tuple describing the C compiler used when @@ -5533,7 +5545,7 @@ true</pre> <c>CpuTopology</c> type to change. </p> </item> - <tag><c>{cpu_topology, defined}</c></tag> + <tag><marker id="system_info_cpu_topology_defined"><c>{cpu_topology, defined}</c></marker></tag> <item> <p>Returns the user defined <c>CpuTopology</c>. For more information see the documentation of @@ -5543,12 +5555,14 @@ true</pre> argument. </p> </item> - <tag><c>{cpu_topology, detected}</c></tag> + <tag><marker id="system_info_cpu_topology_detected"><c>{cpu_topology, detected}</c></marker></tag> <item> <p>Returns the automatically detected <c>CpuTopology</c>. The emulator currently only detects the CPU topology on some newer - linux and solaris systems. For more information see the - documentation of the + Linux, Solaris, FreeBSD, and Windows systems. On Windows system with + more than 32 logical processors the CPU topology is not detected. + </p> + <p>For more information see the documentation of the <seealso marker="#system_info_cpu_topology">cpu_topology</seealso> argument. </p> @@ -5606,52 +5620,16 @@ true</pre> </item> <tag><c>elib_malloc</c></tag> <item> - <p>If the emulator uses the <c>elib_malloc</c> memory - allocator, a list of two-element tuples containing status - information is returned; otherwise, <c>false</c> is - returned. The list currently contains the following - two-element tuples (all sizes are presented in bytes):</p> - <taglist> - <tag><c>{heap_size, Size}</c></tag> - <item> - <p>Where <c>Size</c> is the current heap size.</p> - </item> - <tag><c>{max_alloced_size, Size}</c></tag> - <item> - <p>Where <c>Size</c> is the maximum amount of memory - allocated on the heap since the emulator started.</p> - </item> - <tag><c>{alloced_size, Size}</c></tag> - <item> - <p>Where <c>Size</c> is the current amount of memory - allocated on the heap.</p> - </item> - <tag><c>{free_size, Size}</c></tag> - <item> - <p>Where <c>Size</c> is the current amount of free - memory on the heap.</p> - </item> - <tag><c>{no_alloced_blocks, No}</c></tag> - <item> - <p>Where <c>No</c> is the current number of allocated - blocks on the heap.</p> - </item> - <tag><c>{no_free_blocks, No}</c></tag> - <item> - <p>Where <c>No</c> is the current number of free blocks - on the heap.</p> - </item> - <tag><c>{smallest_alloced_block, Size}</c></tag> - <item> - <p>Where <c>Size</c> is the size of the smallest - allocated block on the heap.</p> - </item> - <tag><c>{largest_free_block, Size}</c></tag> - <item> - <p>Where <c>Size</c> is the size of the largest free - block on the heap.</p> - </item> - </taglist> + <p>This option will be removed in a future release. + The return value will always be <c>false</c> since + the elib_malloc allocator has been removed.</p> + </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="erl#+zdbbl">+zdbbl</seealso> command line + flag to <c>erl</c>.</p> </item> <tag><c>fullsweep_after</c></tag> <item> @@ -5727,11 +5705,34 @@ true</pre> 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><c>logical_processors</c></tag> + <tag><marker id="logical_processors"><c>logical_processors</c></marker></tag> + <item> + <p>Returns the detected number of logical processors configured + on the system. The return value is either an integer, or + the atom <c>unknown</c> if the emulator wasn't able to + detect logical processors configured. + </p> + </item> + <tag><marker id="logical_processors_available"><c>logical_processors_available</c></marker></tag> <item> - <p>Returns the number of logical processors detected on the - system as an integer or the atom <c>unknown</c> if the - emulator wasn't able to detect any. + <p>Returns the detected number of logical processors available to + the Erlang runtime system. The return value is either an + integer, or the atom <c>unknown</c> if the emulator wasn't + able to detect logical processors available. The number + of logical processors available is less than or equal to + the number of <seealso marker="#logical_processors_online">logical + processors online</seealso>. + </p> + </item> + <tag><marker id="logical_processors_online"><c>logical_processors_online</c></marker></tag> + <item> + <p>Returns the detected number of logical processors online on + the system. The return value is either an integer, + or the atom <c>unknown</c> if the emulator wasn't able to + detect logical processors online. The number of logical + processors online is less than or equal to the number of + <seealso marker="#logical_processors">logical processors + configured</seealso>. </p> </item> <tag><c>machine</c></tag> @@ -5936,6 +5937,26 @@ true</pre> <c>get_tcw</c> in "Match Specifications in Erlang", <seealso marker="erts:match_spec#get_tcw">ERTS User's Guide</seealso>.</p> </item> + <tag><marker id="update_cpu_info"><c>update_cpu_info</c></marker></tag> + <item> + <p>The runtime system rereads the CPU information available and + updates its internally stored information about the + <seealso marker="#system_info_cpu_topology_detected">detected CPU + topology</seealso> and the amount of logical processors + <seealso marker="#logical_processors">configured</seealso>, + <seealso marker="#logical_processors_online">online</seealso>, and + <seealso marker="#logical_processors_available">available</seealso>. + If the CPU information has changed since the last time it was read, + the atom <c>changed</c> is returned; otherwise, the atom + <c>unchanged</c> is returned. If the CPU information has changed + you probably want to + <seealso marker="#system_flag_schedulers_online">adjust the amount + of schedulers online</seealso>. You typically want to have as + many schedulers online as + <seealso marker="#logical_processors_available">logical processors + available</seealso>. + </p> + </item> <tag><marker id="system_info_version"><c>version</c></marker></tag> <item> <p>Returns a string containing the version number of the diff --git a/erts/doc/src/notes.xml b/erts/doc/src/notes.xml index 6174917807..1703ce0942 100644 --- a/erts/doc/src/notes.xml +++ b/erts/doc/src/notes.xml @@ -30,6 +30,528 @@ </header> <p>This document describes the changes made to the ERTS application.</p> +<section><title>Erts 5.8.1.2</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> Fix that the documentation top index generator can + handle an Ericsson internal application group. </p> + <p> + Own Id: OTP-8875</p> + </item> + <item> + <p>In embedded mode, on_load handlers that called + <c>code:priv_dir/1</c> or other functions in <c>code</c> + would hang the system. Since the <c>crypto</c> + application now contains an on_loader handler that calls + <c>code:priv_dir/1</c>, including the <c>crypto</c> + application in the boot file would prevent the system + from starting.</p> + <p>Also extended the <c>-init_debug</c> option to print + information about on_load handlers being run to + facilitate debugging.</p> + <p> + Own Id: OTP-8902 Aux Id: seq11703 </p> + </item> + </list> + </section> + +</section> + +<section><title>Erts 5.8.1.1</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> + Windows 2003 and Windows XP pre SP3 would sometimes not + start the Erlang R14B VM at all due to a bug in the cpu + topology detection. The bug affects Windows only, no + other platform is even remotely affected. The bug is now + corrected.</p> + <p> + Own Id: OTP-8876</p> + </item> + </list> + </section> + +</section> + +<section><title>Erts 5.8.1</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> + Very small floating point numbers generated errors when + converting from list to float in some versions of the VM, + this is now corrected so that i.e. + list_to_float("1.0e-324"). returns 0.0 in all versions of + Erlang.</p> + <p> + Own Id: OTP-7178</p> + </item> + <item> + <p> + Windows Vista and Windows 7 file system virtualization, + which makes "old style" windows programs execute in a + file system sandbox, was previously unintentionally + turned on for the Erlang VM. This is now corrected so + that i.e. writes to C:\Program Files\. without + administrator privileges will fail.</p> + <p> + Own Id: OTP-7405</p> + </item> + <item> + <p> + Fix faulty 64-bit integer term output from drivers. Large + 64-bits integers did not generate correct bignums and + could even cause emulator crash. Only affects drivers + using ERL_DRV_INT64 or ERL_DRV_UINT64, introduced in + R13B03.</p> + <p> + Own Id: OTP-8716</p> + </item> + <item> + <p> + Fixed: inet:setopts(S, [{linger,{true,2}}]) returned + {error,einval} for SCTP sockets. The inet_drv had a bug + when checking the option size.</p> + <p> + Own Id: OTP-8726 Aux Id: seq11617 </p> + </item> + <item> + <p>Fix libm linking with --as-needed flag + <p> + When building with "--as-needed" linker flags on Linux + the build will fail. This has now been fixed.</p> + <p> + (Thanks to Christian Faulhammer)</p></p> + <p> + Own Id: OTP-8728</p> + </item> + <item> + <p> + gen_udp:connect/3 was broken for SCTP enabled builds. It + did not detect remote end errors as it should.</p> + <p> + Own Id: OTP-8729</p> + </item> + <item> + <p>Reduce the risk of integer wrapping in bin vheap size + counting.</p> <p>The vheap size series will now use the + golden ratio instead of doubling and fibonacci + sequences.</p> + <p> + Own Id: OTP-8730</p> + </item> + <item> + <p> + ETS ordered_set containing <c>[]</c> as key could cause + strange thing to happen, like an infinite hanging + <c>ets:select</c>.</p> + <p> + Own Id: OTP-8732</p> + </item> + <item> + <p>reference() has been substituted for ref() in the + documentation.</p> + <p> + Own Id: OTP-8733</p> + </item> + <item> + <p> + When a native compiled module called a not loaded + non-native compiled module that had an on_load function, + the export entries were trashed after code loading so on + the next call from the native compiled module to the + non-native compiled the emulator crashed. This bug has + now been fixed.</p> + <p> + Own Id: OTP-8736</p> + </item> + <item> + <p> + HiPE-enabled Erlang VMs running on BSD systems sometimes + generated messages like "Yikes! erts_alloc() returned + misaligned address 0x8016a512c". Fixed. (Thanks to Mikael + Pettersson.)</p> + <p> + Own Id: OTP-8769</p> + </item> + <item> + <p> + A race condition in <c>erts_poll()</c> could cause delay + of poll for I/O.</p> + <p> + Own Id: OTP-8773</p> + </item> + <item> + <p> + Removed some potential vulnerabilities from the Erlang + Port Mapper Daemon (epmd) and straightened up access + control. Also removed hazardous interfaces allowing + anyone on a machine to forcefully unregister other nodes. + This means that the ei_unregister/erl_unregister + interfaces in erl_interface is rendered not only error + prone and mystifying as before, but totally ineffective. + The old behaviour of unchecked node unregistering can be + restored if needed, see epmd documentation for details.</p> + <p> + *** POTENTIAL INCOMPATIBILITY ***</p> + <p> + Own Id: OTP-8780</p> + </item> + <item> + <p> Building in a source tree without prebuilt platform + independent build results failed on the SSL examples + when: </p> <list><item> cross building. This has been + solved by not building the SSL examples during a cross + build. </item><item> building on Windows. </item></list> + <p> + Own Id: OTP-8791</p> + </item> + <item> + <p> + inet:getsockopt for SCTP sctp_default_send_param had a + bug to not initialize required feilds causing random + answers. It is now corrected.</p> + <p> + Own Id: OTP-8795 Aux Id: seq11655 </p> + </item> + <item> + <p> + The hipe_bifs:get_hrvtime/0 BIF now always returns a real + value even if the "perfctr" Linux kernel extension is not + available. It used to return a dummy value. (Thanks to + Mikael Pettersson.)</p> + <p> + Own Id: OTP-8798</p> + </item> + <item> + <p> + Calling a native-code compiled module with an + <c>on_load</c> function could cause a crash. (Thanks to + Mikael Pettersson.)</p> + <p> + Own Id: OTP-8799</p> + </item> + <item> + <p>The emulator could crash while writing a crash dump if + native-compiled modules had been loaded. (Thanks to Paul + Guyot.)</p> + <p> + Own Id: OTP-8801</p> + </item> + <item> + <p> + The garbage collector could crash if invoked from + native-compiled code after a call to a BIF. (Thanks to + Paul Guyot.)</p> + <p> + Own Id: OTP-8821</p> + </item> + <item> + <p> + A rare memory leak in binary:matches is removed</p> + <p> + Own Id: OTP-8823</p> + </item> + <item> + <p>For a socket in the HTTP packet mode, the return value + from <c>gen_tcp:recv/2,3</c> if there is an error in the + header will be <c>{ok,{http_error,String}}</c> instead of + <c>{error,{http_error,String}}</c> to be consistent with + <c>ssl:recv/2,3</c>.</p> + <p> + *** POTENTIAL INCOMPATIBILITY ***</p> + <p> + Own Id: OTP-8831</p> + </item> + </list> + </section> + + + <section><title>Improvements and New Features</title> + <list> + <item> + <p> + ets:select_reverse/{1,2,3} are now documented.</p> + <p> + Own Id: OTP-7863</p> + </item> + <item> + <p> + External format of integers changed to make full use of + all 32 bits of INTEGER_EXT. This is a compatible change + as old code can read full 32-bit integers but only + produce 28-bit integers as INTEGER_EXT.</p> + <p> + Own Id: OTP-8540 Aux Id: seq11534 </p> + </item> + <item> + <p> + Large parts of the <c>ethread</c> library have been + rewritten. The <c>ethread</c> library is an Erlang + runtime system internal, portable thread library used by + the runtime system itself.</p> + <p> + Most notable improvement is a reader optimized rwlock + implementation which dramatically improve the performance + of read-lock/read-unlock operations on multi processor + systems by avoiding ping-ponging of the rwlock cache + lines. The reader optimized rwlock implementation is used + by miscellaneous rwlocks in the runtime system that are + known to be read-locked frequently, and can be enabled on + ETS tables by passing the <seealso + marker="stdlib:ets#new_2_read_concurrency">{read_concurrency, + true}</seealso> option upon table creation. See the + documentation of <seealso + marker="stdlib:ets#new/2">ets:new/2</seealso> for more + information. The reader optimized rwlock implementation + can be fine tuned when starting the runtime system. For + more information, see the documentation of the <seealso + marker="erts:erl#+rg">+rg</seealso> command line argument + of <c>erl</c>.</p> + <p> + There is also a new implementation of rwlocks that is not + optimized for readers. Both implementations interleaves + readers and writers during contention as opposed to, + e.g., the NPTL (Linux) pthread rwlock implementation + which use either a reader or writer preferred strategy. + The reader/writer preferred strategy is problematic since + it starves threads doing the non-preferred operation.</p> + <p> + The new rwlock implementations in general performs better + in ERTS than common pthread implementations. However, in + some extremely heavily contended cases this is not the + case. Such heavy contention can more or less only appear + on ETS tables. This when multiple processes do very large + amounts of write locked operations simultaneously on the + same table. Such use of ETS is bad regardless of rwlock + implementation, will never scale, and is something we + strongly advise against.</p> + <p> + The new rwlock implementations depend on atomic + operations. If no native atomic implementation is found, + a fallback solution will be used. Using the fallback + implies a performance degradation. That is, it is more + important now than before to build OTP with a native + atomic implementation.</p> + <p> + The <c>ethread</c> library contains native atomic + implementations for, x86 (32 and 64 bit), powerpc (32 + bit), sparc V9 (32 and 64 bit), and tilera (32 bit). On + other hardware gcc's builtin support for atomic memory + access will be used if such exists. If no such support is + found, <c>configure</c> will warn about no atomic + implementation available.</p> + <p> + The <c>ethread</c> library can now also use the + <c>libatomic_ops</c> library for atomic memory accesses. + This makes it possible for the Erlang runtime system to + utilize optimized native atomic operations on more + platforms than before. If <c>configure</c> warns about no + atomic implementation available, try using the + <c>libatomic_ops</c> library. Use the <seealso + marker="doc/installation_guide:INSTALL#How-to-Build-and-Install-ErlangOTP_A-Closer-Look-at-the-individual-Steps_Configuring">--with-libatomic_ops=PATH</seealso> + <c>configure</c> command line argument when specifying + where the <c>libatomic_ops</c> installation is located. + The <c>libatomic_ops</c> library can be downloaded from: + <url + href="http://www.hpl.hp.com/research/linux/atomic_ops/">http://www.hpl.hp.com/research/linux/atomic_ops/</url></p> + <p> + The changed API of the <c>ethread</c> library has also + caused modifications in the Erlang runtime system. + Preparations for the to come "delayed deallocation" + feature has also been done since it depends on the + <c>ethread</c> library.</p> + <p> + <em>Note</em>: When building for x86, the <c>ethread</c> + library will now use instructions that first appeared on + the pentium 4 processor. If you want the runtime system + to be compatible with older processors (back to 486) you + need to pass the <seealso + marker="doc/installation_guide:INSTALL#How-to-Build-and-Install-ErlangOTP_A-Closer-Look-at-the-individual-Steps_Configuring">--enable-ethread-pre-pentium4-compatibility</seealso> + <c>configure</c> command line argument when configuring + the system.</p> + <p> + Own Id: OTP-8544</p> + </item> + <item> + <p> + erlang:localtime_to_universaltime({{2008, 8, 1}, {0, 0, + 0}},true) when TZ=UTC now behaves consistently on all + Unix platforms.</p> + <p> + The problem fixed was originally reported by Paul Guyot + on erlang-bugs mailing list:</p> + <p> + http://www.erlang.org/pipermail/erlang-bugs/2008-November/001077.html</p> + <p> + Own Id: OTP-8580</p> + </item> + <item> + <p> + Optimization reducing memory consumption by two words per + ETS object.</p> + <p> + Own Id: OTP-8737</p> + </item> + <item> + <p> + Fixes for unsupported halfword-emulator</p> + <p> + Own Id: OTP-8745</p> + </item> + <item> + <p> + NIF 64-bit integer support; <c>enif_get_int64</c>, + <c>enif_get_uint64</c>, <c>enif_make_int64</c>, + <c>enif_make_uint64</c>.</p> + <p> + Own Id: OTP-8746</p> + </item> + <item> + <p> + Alignment of trailing data in messages has been adjusted. + This in order to be able to pass data of any type as + trailing data in the future.</p> + <p> + Own Id: OTP-8754</p> + </item> + <item> + <p> + The obsolete/driver.h header file has been removed. It + has been obsolete and deprecated since R8B. Drivers that + still include obsolete/driver.h must be updated to + include erl_driver.h.</p> + <p> + *** POTENTIAL INCOMPATIBILITY ***</p> + <p> + Own Id: OTP-8758</p> + </item> + <item> + <p> + Added erlang:system_info(build_type) which makes it + easier to chose drivers, NIF libraries, etc based on + build type of the runtime system.</p> + <p> + The NIF library for crypto can now be built for valgrind + and/or debug as separate NIF libraries that will be + automatically loaded if the runtime system has been built + with a matching build type.</p> + <p> + Own Id: OTP-8760</p> + </item> + <item> + <p> + Further lessened the memory requirements of ETS objects.</p> + <p> + Own Id: OTP-8762</p> + </item> + <item> + <p>The broken elib_malloc alternate memory allocator has + been removed. <c>erlang:system_info(elib_malloc)</c> will + always return <c>false</c>, and in R15, + <c>erlang:system_info(elib_malloc)</c> will fail with a + <c>badarg</c> exception.</p> + <p> + Own Id: OTP-8764</p> + </item> + <item> + <p> + Calling <c>erlang:system_info/1</c> with the new argument + <c>update_cpu_info</c> will make the runtime system + reread and update the internally stored CPU information. + For more information see the documentation of <seealso + marker="erlang#update_cpu_info">erlang:system_info(update_cpu_info)</seealso>.</p> + <p> + The CPU topology is now automatically detected on Windows + systems with less than 33 logical processors. The runtime + system will now, also on Windows, by default bind + schedulers to logical processors using the + <c>default_bind</c> bind type if the amount of schedulers + is at least equal to the amount of logical processors + configured, binding of schedulers is supported, and a CPU + topology is available at startup.</p> + <p> + Own Id: OTP-8765</p> + </item> + <item> + <p> + The SMP ERTS internal child waiter thread used on Linux + system with NPTL was unintentionally disabled during + cross compilation rewrites (OTP-8323 in R13B03). It has + now been re-enabled. Enabling it again gives a slight + performance improvement.</p> + <p> + Own Id: OTP-8774</p> + </item> + <item> + <p> + <c>epmd</c> used to generate a message to the syslog when + it started up, which could be annoying. This has been + changed to only generate the message if the debug swith + is given. (Thanks to Michael Santos.)</p> + <p> + Own Id: OTP-8775</p> + </item> + <item> + <p> + The scheduler wakeup threshold is now possible to adjust + at system boot. For more information see the <seealso + marker="erl#+swt">+swt</seealso> command line argument of + <c>erl</c>.</p> + <p> + Own Id: OTP-8811</p> + </item> + <item> + <p> + The undocumented function inet:ifget/2 has been improved + to return interface hardware address (MAC) on platforms + supporting getaddrinfo() (such as BSD unixes). Note it + still does not work on all platforms for example not + Windows nor Solaris, so the function is still + undocumented.</p> + <p> + Buffer overflow and field init bugs for inet:ifget/2 and + inet:getservbyname/2 has also been fixed.</p> + <p> + Thanks to Michael Santos.</p> + <p> + Own Id: OTP-8816</p> + </item> + <item> + <p> + Optimizations for MIPS when using gcc atomics. (Thanks to + Steve Vinoski)</p> + <p> + Own Id: OTP-8834</p> + </item> + <item> + <p> + Lock optimization in timer functionality.</p> + <p> + Own Id: OTP-8835</p> + </item> + </list> + </section> + + + <section><title>Known Bugs and Problems</title> + <list> + <item> + <p>Fix epmd and build environment to build on VxWorks</p> + <p> + Own Id: OTP-8838</p> + </item> + </list> + </section> + +</section> + <section><title>Erts 5.8</title> <section><title>Fixed Bugs and Malfunctions</title> |