diff options
Diffstat (limited to 'system')
| -rw-r--r-- | system/README | 11 | ||||
| -rw-r--r-- | system/doc/efficiency_guide/advanced.xml | 26 | ||||
| -rw-r--r-- | system/doc/efficiency_guide/drivers.xml | 16 | ||||
| -rw-r--r-- | system/doc/embedded/part.xml | 3 | ||||
| -rw-r--r-- | system/doc/embedded/vxworks.xml | 193 | ||||
| -rw-r--r-- | system/doc/embedded/xmlfiles.mk | 5 | ||||
| -rw-r--r-- | system/doc/installation_guide/Makefile | 8 | ||||
| -rw-r--r-- | system/doc/installation_guide/part.xml | 6 | ||||
| -rw-r--r-- | system/doc/installation_guide/xmlfiles.mk | 5 | ||||
| -rw-r--r-- | system/doc/reference_manual/data_types.xml | 12 | ||||
| -rw-r--r-- | system/doc/reference_manual/expressions.xml | 11 | ||||
| -rw-r--r-- | system/doc/reference_manual/introduction.xml | 13 | ||||
| -rw-r--r-- | system/doc/reference_manual/ports.xml | 15 | ||||
| -rw-r--r-- | system/doc/reference_manual/typespec.xml | 359 | ||||
| -rw-r--r-- | system/doc/top/Makefile | 6 |
15 files changed, 275 insertions, 414 deletions
diff --git a/system/README b/system/README index b8ff18119d..61277306f1 100644 --- a/system/README +++ b/system/README @@ -1,7 +1,7 @@ -Erlang/OTP December 8, 2011 +Erlang/OTP Januari 25, 2013 -Release of Erlang 5.9/OTP R15B +Release of Erlang 5.10/OTP R16 1. GENERAL @@ -51,10 +51,9 @@ Release of Erlang 5.9/OTP R15B ------------------------------- 3.1 The platform VxWorks is discontinued in the sense that only the - libraries (erl_interface and ic's libraries) are supported. Running - the Erlang emulator on VxWorks might still possible but it's no longer - maintained. The VxWorks release is still packaged as a full release, - but no support will be available for anything but the communication libraries. + libraries (erl_interface and ic's libraries) are supported. The VxWorks + release is still packaged as a full release, but no support will be + available for anything but the communication libraries. 4 NOTES ABOUT THE LINUX VERSIONS ----------------------------- diff --git a/system/doc/efficiency_guide/advanced.xml b/system/doc/efficiency_guide/advanced.xml index 821175bb09..3bbaf7a0ad 100644 --- a/system/doc/efficiency_guide/advanced.xml +++ b/system/doc/efficiency_guide/advanced.xml @@ -4,7 +4,7 @@ <chapter> <header> <copyright> - <year>2001</year><year>2011</year> + <year>2001</year><year>2013</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -123,12 +123,11 @@ On 64-bit architectures: 4 words for a reference from the current local node, an <tag><em>Processes</em></tag> <item> <p>The maximum number of simultaneously alive Erlang processes is - by default 32768. This limit can be raised up to at most 268435456 - processes at startup (see documentation of the system flag - <seealso marker="erts:erl#max_processes">+P</seealso> in the - <seealso marker="erts:erl">erl(1)</seealso> documentation). - The maximum limit of 268435456 processes will at least on a 32-bit - architecture be impossible to reach due to memory shortage.</p> + by default 32768. This limit can be configured at startup, + for more information see the + <seealso marker="erts:erl#max_processes"><c>+P</c></seealso> + command line flag of + <seealso marker="erts:erl"><c>erl(1)</c></seealso>.</p> </item> <tag><em>Distributed nodes</em></tag> <item> @@ -184,13 +183,12 @@ On 64-bit architectures: 4 words for a reference from the current local node, an <tag><em>Open ports</em></tag> <item> <marker id="ports"></marker> - <p>The maximum number of simultaneously open Erlang ports is - by default 1024. This limit can be raised up to at most 268435456 - at startup (see environment variable - <seealso marker="erts:erlang#ERL_MAX_PORTS">ERL_MAX_PORTS</seealso> - in <seealso marker="erts:erlang">erlang(3)</seealso>) - The maximum limit of 268435456 open ports will at least on a 32-bit - architecture be impossible to reach due to memory shortage.</p> + <p>The maximum number of simultaneously oper Erlang ports is + often by default 16384. This limit can be configured at startup, + for more information see the + <seealso marker="erts:erl#max_ports"><c>+Q</c></seealso> + command line flag of + <seealso marker="erts:erl"><c>erl(1)</c></seealso>.</p> </item> <tag><em>Open files, and sockets</em></tag> <item> <marker id="files_sockets"></marker> diff --git a/system/doc/efficiency_guide/drivers.xml b/system/doc/efficiency_guide/drivers.xml index fec68ca059..66311a3738 100644 --- a/system/doc/efficiency_guide/drivers.xml +++ b/system/doc/efficiency_guide/drivers.xml @@ -4,7 +4,7 @@ <chapter> <header> <copyright> - <year>2009</year><year>2011</year> + <year>2009</year><year>2013</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -105,9 +105,9 @@ client_port() -> <p>If you know that the binaries you return are always small, you should use driver API calls that do not require a pre-allocated binary, for instance - <seealso marker="erts:erl_driver#int driver_output-3">driver_output()</seealso> + <seealso marker="erts:erl_driver#driver_output">driver_output()</seealso> or - <seealso marker="erts:erl_driver#int driver_output_term-3">driver_output_term()</seealso> + <seealso marker="erts:erl_driver#erl_drv_output_term">erl_drv_output_term()</seealso> using the <c>ERL_DRV_BUF2BINARY</c> format, to allow the run-time to construct a heap binary.</p> @@ -120,7 +120,7 @@ client_port() -> the driver to an Erlang process, the driver must first allocate the binary and then send it to an Erlang process in some way.</p> - <p>Use <seealso marker="erts:erl_driver#ErlDrvBinary* driver_alloc_binary-1">driver_alloc_binary()</seealso> to allocate a binary.</p> + <p>Use <seealso marker="erts:erl_driver#driver_alloc_binary">driver_alloc_binary()</seealso> to allocate a binary.</p> <p>There are several ways to send a binary created with <c>driver_alloc_binary()</c>.</p> @@ -128,17 +128,17 @@ client_port() -> <list type="bulleted"> <item><p>From the <c>control</c> callback, a binary can be returned provided that - <seealso marker="erts:erl_driver#void set_port_control_flags-2">set_port_control()</seealso> + <seealso marker="erts:erl_driver#set_port_control_flags">set_port_control_flags()</seealso> has been called with the flag value <c>PORT_CONTROL_FLAG_BINARY</c>.</p> </item> <item><p>A single binary can be sent with - <seealso marker="erts:erl_driver#int driver_output_binary-6">driver_output_binary()</seealso>.</p></item> + <seealso marker="erts:erl_driver#driver_output_binary">driver_output_binary()</seealso>.</p></item> <item><p>Using - <seealso marker="erts:erl_driver#int driver_output_term-3">driver_output_term()</seealso> + <seealso marker="erts:erl_driver#erl_drv_output_term">erl_drv_output_term()</seealso> or - <seealso marker="erts:erl_driver#int driver_send_term-4">driver_send_term()</seealso>, + <seealso marker="erts:erl_driver#erl_drv_send_term">erl_drv_send_term()</seealso>, a binary can be included in an Erlang term.</p> </item> </list> diff --git a/system/doc/embedded/part.xml b/system/doc/embedded/part.xml index abedce46d6..6dd0b73965 100644 --- a/system/doc/embedded/part.xml +++ b/system/doc/embedded/part.xml @@ -4,7 +4,7 @@ <part xmlns:xi="http://www.w3.org/2001/XInclude"> <header> <copyright> - <year>1997</year><year>2009</year> + <year>1997</year><year>2013</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -45,6 +45,5 @@ </description> <xi:include href="embedded_solaris.xml"/> <xi:include href="embedded_nt.xml"/> - <xi:include href="vxworks.xml"/> </part> diff --git a/system/doc/embedded/vxworks.xml b/system/doc/embedded/vxworks.xml deleted file mode 100644 index 52143a42e3..0000000000 --- a/system/doc/embedded/vxworks.xml +++ /dev/null @@ -1,193 +0,0 @@ -<?xml version="1.0" encoding="latin1" ?> -<!DOCTYPE chapter SYSTEM "chapter.dtd"> - -<chapter> - <header> - <copyright> - <year>1997</year><year>2009</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>VxWorks</title> - <prepared>Patrik Winroth</prepared> - <responsible></responsible> - <docno></docno> - <approved></approved> - <checked></checked> - <date>2000-10-17</date> - <rev></rev> - <file>vxworks.xml</file> - </header> - <p>This chapter describes the OS specific parts of OTP which relate - to VxWorks. - </p> - - <section> - <title>Introduction</title> - <p>The Erlang/OTP distribution for VxWorks is limited to what - Switchboard requires (Switchboard is a general purpose - switching hardware developed by Ericsson). - </p> - <p>Please consult the README file, included at root level in the - installation, for latest information on the distribution. - </p> - </section> - - <section> - <title>Memory Usage</title> - <p>Memory required is 32 Mbyte. - </p> - </section> - - <section> - <title>Disk Usage</title> - <p>The disk space required is 22 Mbyte, the documentation included. - </p> - </section> - - <section> - <title>Installation</title> - <p>OTP/VxWorks is supplied in a distribution file named - <c><![CDATA[<PREFIX>.tar.gz]]></c>; i.e. a tar archive that is - compressed with gzip. <c><![CDATA[<PREFIX>]]></c> represents the - name of the release, - e.g. <c>otp_LXA12345_vxworks_cpu32_R42A</c>. Assuming you are - installing to a Solaris file system, the installation is - performed by following these steps: < - </p> - <p></p> - <list type="bulleted"> - <item>Change to the directory where you want to install - OTP/VxWorks (<c><![CDATA[<ROOTDIR>]]></c>): <c><![CDATA[cd <ROOTDIR>]]></c></item> - <item>Make a directory to put OTP/VxWorks in: <c>mkdir otp_vxworks_cpu32</c> (or whatever you want to call it)</item> - <item>Change directory to the newly created one: <c>cd otp_vxworks_cpu32</c></item> - <item>Copy the distribution file there from where it is located - (<c><![CDATA[<RELDIR>]]></c>): <c><![CDATA[cp <RELDIR>/<PREFIX>.tar.gz .]]></c></item> - <item>Unzip the distribution file: <c><![CDATA[gunzip <PREFIX>.tar.gz]]></c></item> - <item>Untar <c><![CDATA[<PREFIX>.tar]]></c>: <c><![CDATA[tar xvf <PREFIX>.tar]]></c></item> - <item>Create a bin directory: <c>mkdir bin</c></item> - <item>Copy the VxWorks Erlang/OTP start-up script to the bin directory: - <c>cp erts-Vsn/bin/erl bin/.</c></item> - <item>Copy the example start scripts to the bin directory: - <c>cp releases/R42A/*.boot bin/.</c></item> - </list> - <p>If you use VxWorks nfs mounting facility to mount the Solaris - file system, this installation may be directly used. An other - possibility is to copy the installation to a local VxWorks DOS - file system, from where it is used. - </p> - </section> - - <section> - <title>OS Specific Functionality/Information</title> - <p>There are a couple of files that are unique to the VxWorks - distribution of Erlang/OTP, these files are described here. - </p> - <list type="bulleted"> - <item>README - this files has some information on VxWorks - specifics that you are advised to consult. This includes the - latest information on what parts of OTP are included in the - VxWorks distribution of Erlang/OTP. If you want us to - include more parts, please contact us to discuss - this.</item> - <item>erts-Vsn/bin/resolv.conf - A resolver configuration EXAMPLE file. - You have to edit this file.</item> - <item>erts-Vsn/bin/erl - This is an EXAMPLE start script for VxWorks. - You have to edit this file to suit your needs.</item> - <item>erts-Vsn/bin/erl_io - One possible solution to the problem - of competing Erlang and VxWorks shell. Contains the function - 'start_erl' called by the erl script. Also contains the - function 'to_erl' to be used when connecting to the Erlang - shell from VxWorks' shell.</item> - <item>erts-Vsn/bin/erl_exec - Rearranges command line arguments - and starts Erlang.</item> - <item>erts-Vsn/bin/vxcall - Allows spawning of standard VxWorks - shell functions (which is just about any function in the - system...) from open_port/2. E.g. open_port({spawn, 'vxcall - func arg1 arg2'}, []) will cause the output that 'func arg1, - arg2' would have given in the shell to be received from the - port.</item> - <item>erts-Vsn/bin/rdate - Set the time from a networked host, - like the SunOS command. Nothing Erlang-specific, but nice - if you want date/0 and time/0 to give meaningful values (you - also need a TIMEZONE environment setting if GMT isn't - acceptable). For example: <c>putenv "TIMEZONE=CET::-60:033002:102603"</c> sets central european - time.</item> - <item>erts-Vsn/src - Contains source for the above files, and - additionally config.c, driver.h, preload.c and - reclaim.h. Reclaim.h defines the interface to a simple - mechanism for "resource reclamation" that is part of the - Erlang runtime system - may be useful to "port program" writers (and - possibly others). Take careful note of the caveats listed in - the file!</item> - </list> - </section> - - <section> - <title>Starting Erlang</title> - <p>Start (and restart) of the system depends on what file system - is used. To be able to start the system from a nfs mounted - file system you can use VxWorks start script facility to run a - start script similar to the example below. Note that the - Erlang/OTP start-up script is run at the end of this script. - </p> - <code type="none"><![CDATA[ -# start.script v1.0 1997/09/08 patrik -# -# File name: start.script -# Purpose: Starting the VxWorks/cpu32 erlang/OTP -# Author: [email protected] -# Resides in: ~tornado/wind/target/config/ads360/ - -# -# Set shell prompt -# -shellPromptSet("sauron-> ") - -# -# Set default gateway -# -hostAdd "router-20","150.236.20.251" -routeAdd "0","router-20" - -# -# Mount /home from gandalf -# -hostAdd "gandalf","150.236.20.16" -usergroup=10 -nfsAuthUnixSet("gandalf", 452, 10, 1, &usergroup) -nfsMount("gandalf", "/export/home", "/home") - -# -# Load and run rdate.o to set correct date on the target -# -ld < /home/gandalf/tornado/wind/target/config/ads360/rdate.o -rdate("gandalf") - -# -# Setup timezone information (Central European time) -# -putenv "TIMEZONE=CET::-60:033002:102603" - -# -# Run the Erlang/OTP start script -# -cd "/home/gandalf/tornado/wind/target/erlang_cpu32_R42A/bin" -<erl - ]]></code> - </section> -</chapter> - diff --git a/system/doc/embedded/xmlfiles.mk b/system/doc/embedded/xmlfiles.mk index 2bdc34ae28..d11f5a1004 100644 --- a/system/doc/embedded/xmlfiles.mk +++ b/system/doc/embedded/xmlfiles.mk @@ -1,7 +1,7 @@ # # %CopyrightBegin% # -# Copyright Ericsson AB 2009. All Rights Reserved. +# Copyright Ericsson AB 2009-2013. All Rights Reserved. # # The contents of this file are subject to the Erlang Public License, # Version 1.1, (the "License"); you may not use this file except in @@ -18,5 +18,4 @@ # EMBEDDED_CHAPTER_FILES = \ embedded_solaris.xml \ - embedded_nt.xml \ - vxworks.xml + embedded_nt.xml diff --git a/system/doc/installation_guide/Makefile b/system/doc/installation_guide/Makefile index 8affeaf10a..6923f52d8a 100644 --- a/system/doc/installation_guide/Makefile +++ b/system/doc/installation_guide/Makefile @@ -58,7 +58,8 @@ XML_FILES = \ GENERATED_XML_FILES = \ INSTALL.xml \ INSTALL-CROSS.xml \ - INSTALL-WIN32.xml + INSTALL-WIN32.xml \ + MARKDOWN.xml # ---------------------------------------------------- @@ -73,7 +74,8 @@ REDIRECT_HTML_DIR = $(HTMLDIR)/source REDIRECT_HTML_FILES = \ $(REDIRECT_HTML_DIR)/INSTALL.html \ $(REDIRECT_HTML_DIR)/INSTALL-CROSS.html \ - $(REDIRECT_HTML_DIR)/INSTALL-WIN32.html + $(REDIRECT_HTML_DIR)/INSTALL-WIN32.html \ + $(REDIRECT_HTML_DIR)/MARKDOWN.html # ---------------------------------------------------- # FLAGS @@ -85,7 +87,7 @@ DVIPS_FLAGS += # Targets # ---------------------------------------------------- -%.xml: $(ERL_TOP)/%.md $(ERL_TOP)/make/emd2exml +%.xml: $(ERL_TOP)/HOWTO/%.md $(ERL_TOP)/make/emd2exml $(ERL_TOP)/make/emd2exml $< $@ $(REDIRECT_HTML_DIR)/%.html: Makefile diff --git a/system/doc/installation_guide/part.xml b/system/doc/installation_guide/part.xml index fceacdd8f6..2cffd30283 100644 --- a/system/doc/installation_guide/part.xml +++ b/system/doc/installation_guide/part.xml @@ -4,7 +4,7 @@ <part xmlns:xi="http://www.w3.org/2001/XInclude"> <header> <copyright> - <year>2000</year><year>2010</year> + <year>2000</year><year>2013</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -36,5 +36,5 @@ <xi:include href="INSTALL.xml"/> <xi:include href="INSTALL-CROSS.xml"/> <xi:include href="INSTALL-WIN32.xml"/> -</part> - + <xi:include href="MARKDOWN.xml"/> +</part>
\ No newline at end of file diff --git a/system/doc/installation_guide/xmlfiles.mk b/system/doc/installation_guide/xmlfiles.mk index dee67b3c70..3995c607af 100644 --- a/system/doc/installation_guide/xmlfiles.mk +++ b/system/doc/installation_guide/xmlfiles.mk @@ -1,7 +1,7 @@ # # %CopyrightBegin% # -# Copyright Ericsson AB 2009-2010. All Rights Reserved. +# Copyright Ericsson AB 2009-2013. All Rights Reserved. # # The contents of this file are subject to the Erlang Public License, # Version 1.1, (the "License"); you may not use this file except in @@ -21,4 +21,5 @@ INST_GUIDE_CHAPTER_FILES = \ verification.xml \ INSTALL.xml \ INSTALL-CROSS.xml \ - INSTALL-WIN32.xml + INSTALL-WIN32.xml \ + MARKDOWN.xml diff --git a/system/doc/reference_manual/data_types.xml b/system/doc/reference_manual/data_types.xml index df1c0f8fa8..531d50b2cf 100644 --- a/system/doc/reference_manual/data_types.xml +++ b/system/doc/reference_manual/data_types.xml @@ -4,7 +4,7 @@ <chapter> <header> <copyright> - <year>2003</year><year>2009</year> + <year>2003</year><year>2013</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -393,7 +393,15 @@ hello 12> <input>term_to_binary({a,b,c}).</input> <<131,104,3,100,0,1,97,100,0,1,98,100,0,1,99>> 13> <input>binary_to_term(<<131,104,3,100,0,1,97,100,0,1,98,100,0,1,99>>).</input> -{a,b,c}</pre> +{a,b,c} +14> <input>binary_to_integer(<<"77">>).</input> +77 +15> <input>integer_to_binary(77).</input> +<<"77">> +16> <input>float_to_binary(7.0).</input> +<<"7.00000000000000000000e+00">> +17> <input>binary_to_float(<<"7.000e+00>>").</input> +7.0</pre> </section> </chapter> diff --git a/system/doc/reference_manual/expressions.xml b/system/doc/reference_manual/expressions.xml index d564b20ca6..357f89f731 100644 --- a/system/doc/reference_manual/expressions.xml +++ b/system/doc/reference_manual/expressions.xml @@ -236,10 +236,6 @@ Fun1 = fun(X) -> X+1 end Fun1(3) => 4 -Fun2 = {lists,append} -Fun2([1,2], [3,4]) -=> [1,2,3,4] - fun lists:append/2([1,2], [3,4]) => [1,2,3,4]</code> @@ -1000,13 +996,6 @@ fun (Arg1,...,ArgN) -> Name(Arg1,...,ArgN) end</pre> <c>Module</c>. A fun defined in this way will not be dependent on the code for module in which it is defined. </p> - <p>When applied to a number N of arguments, a tuple - <c>{Module,FunctionName}</c> is interpreted as a fun, referring - to the function <c>FunctionName</c> with arity N in the module - <c>Module</c>. The function must be exported. - <em>This usage is deprecated.</em> Use <c>fun Module:Name/Arity</c> - instead. - See <seealso marker="#calls">Function Calls</seealso> for an example.</p> <p>More examples can be found in <em>Programming Examples</em>.</p> </section> diff --git a/system/doc/reference_manual/introduction.xml b/system/doc/reference_manual/introduction.xml index 3dac5cfe13..7737c34469 100644 --- a/system/doc/reference_manual/introduction.xml +++ b/system/doc/reference_manual/introduction.xml @@ -4,7 +4,7 @@ <chapter> <header> <copyright> - <year>2003</year><year>2009</year> + <year>2003</year><year>2012</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -150,6 +150,17 @@ </row> <tcaption>Character Classes.</tcaption> </table> + <p>In Erlang/OTP R16 the syntax of Erlang tokens was extended to + handle Unicode. To begin with the support is limited to strings, + but Erlang/OTP R18 is expected to handle Unicode atoms as well. + More about the usage of Unicode in Erlang source files can be + found in <seealso + marker="stdlib:unicode_usage#unicode_in_erlang">STDLIB's User'S + Guide</seealso>. The default encoding for Erlang source files + is still Latin-1, but in Erlang/OTP R17 the default encoding + will be UTF-8. The details on how to state the encoding of an + Erlang source file can be found in <seealso + marker="stdlib:epp#encoding">epp(3)</seealso>.</p> </section> </chapter> diff --git a/system/doc/reference_manual/ports.xml b/system/doc/reference_manual/ports.xml index 4847dd67cd..58e2baac17 100644 --- a/system/doc/reference_manual/ports.xml +++ b/system/doc/reference_manual/ports.xml @@ -4,7 +4,7 @@ <chapter> <header> <copyright> - <year>2004</year><year>2009</year> + <year>2004</year><year>2013</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -87,8 +87,14 @@ of bytes, the option <c>binary</c> must be included.</p> <p>The port owner <c>Pid</c> can communicate with the port <c>Port</c> by sending and receiving messages. (In fact, any - process can send the messages to the port, but the messages from - the port always go to the port owner).</p> + process can send the messages to the port, but the port owner must + be identified in the message).</p> + <p>As of OTP-R16 messages sent to ports are delivered truly + asynchronously. The underlying implementation previously + delivered messages to ports synchronously. Message passing has + however always been documented as an asynchronous operation, so + this should not be an issue for an Erlang program communicating + with ports, unless false assumptions about ports has been made.</p> <p>Below, <c>Data</c> must be an I/O list. An I/O list is a binary or a (possibly deep) list of binaries or integers in the range 0..255.</p> @@ -127,8 +133,7 @@ <tcaption>Messages Received From a Port.</tcaption> </table> <p>Instead of sending and receiving messages, there are also a - number of BIFs that can be used. These can be called by any - process, not only the port owner.</p> + number of BIFs that can be used.</p> <table> <row> <cell align="left" valign="middle"><c>port_command(Port,Data)</c></cell> diff --git a/system/doc/reference_manual/typespec.xml b/system/doc/reference_manual/typespec.xml index c3620f83f6..1279493ba8 100644 --- a/system/doc/reference_manual/typespec.xml +++ b/system/doc/reference_manual/typespec.xml @@ -1,10 +1,10 @@ -<?xml version="1.0" encoding="latin1" ?> +<?xml version="1.0" encoding="iso-8859-1" ?> <!DOCTYPE chapter SYSTEM "chapter.dtd"> <chapter> <header> <copyright> - <year>2003</year><year>2011</year> + <year>2003</year><year>2013</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -13,12 +13,12 @@ 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>Types and Function Specifications</title> @@ -30,111 +30,121 @@ </header> <section> - <title>Introduction of Types</title> - <p> - Erlang is a dynamically typed language. Still, it comes with a - language extension for declaring sets of Erlang terms to form a - particular type, effectively forming a specific sub-type of the set - of all Erlang terms. - </p> - <p> - Subsequently, these types can be used to specify types of record fields - and the argument and return types of functions. - </p> - <p> - Type information can be used to document function interfaces, - provide more information for bug detection tools such as <c>Dialyzer</c>, - and can be exploited by documentation tools such as <c>Edoc</c> for - generating program documentation of various forms. - It is expected that the type language described in this document will - supersede and replace the purely comment-based <c>@type</c> and - <c>@spec</c> declarations used by <c>Edoc</c>. - </p> + <title>The Erlang Type Language</title> + <p> + Erlang is a dynamically typed language. Still, it comes with a + notation for declaring sets of Erlang terms to form a particular + type, effectively forming a specific sub-type of the set of all + Erlang terms. + </p> + <p> + Subsequently, these types can be used to specify types of record fields + and the argument and return types of functions. + </p> + <p> + Type information can be used to document function interfaces, + provide more information for bug detection tools such as <c>Dialyzer</c>, + and can be exploited by documentation tools such as <c>Edoc</c> for + generating program documentation of various forms. + It is expected that the type language described in this document will + supersede and replace the purely comment-based <c>@type</c> and + <c>@spec</c> declarations used by <c>Edoc</c>. + </p> </section> <section> <marker id="syntax"></marker> <title>Types and their Syntax</title> <p> - Types describe sets of Erlang terms. - Types consist and are built from a set of predefined types (e.g. <c>integer()</c>, - <c>atom()</c>, <c>pid()</c>, ...) described below. - Predefined types represent a typically infinite set of Erlang terms which - belong to this type. - For example, the type <c>atom()</c> stands for the set of all Erlang atoms. - </p> - <p> - For integers and atoms, we allow for singleton types (e.g. the integers <c>-1</c> - and <c>42</c> or the atoms <c>'foo'</c> and <c>'bar'</c>). + Types describe sets of Erlang terms. + Types consist and are built from a set of predefined types + (e.g. <c>integer()</c>, <c>atom()</c>, <c>pid()</c>, ...) + described below. + Predefined types represent a typically infinite set of Erlang terms which + belong to this type. For example, the type <c>atom()</c> stands for the + set of all Erlang atoms. + </p> + <p> + For integers and atoms, we allow for singleton types (e.g. the integers + <c>-1</c> and <c>42</c> or the atoms <c>'foo'</c> and <c>'bar'</c>). - All other types are built using unions of either predefined types or singleton - types. In a type union between a type and one of its sub-types the sub-type is - absorbed by the super-type and the union is subsequently treated as if the - sub-type was not a constituent of the union. For example, the type union: + All other types are built using unions of either predefined + types or singleton types. In a type union between a type and one + of its sub-types the sub-type is absorbed by the super-type and + the union is subsequently treated as if the sub-type was not a + constituent of the union. For example, the type union: </p> - <pre> - atom() | 'bar' | integer() | 42</pre> - <p> - describes the same set of terms as the type union: - </p> - <pre> -atom() | integer()</pre> - <p> - Because of sub-type relations that exist between types, types form a lattice - where the topmost element, any(), denotes the set of all Erlang terms and - the bottom-most element, none(), denotes the empty set of terms. - </p> - <p> - The set of predefined types and the syntax for types is given below: - </p> - <pre><![CDATA[ -Type :: any() %% The top type, the set of all Erlang terms. - | none() %% The bottom type, contains no terms. - | pid() - | port() - | reference() - | [] %% nil - | Atom - | Binary - | float() - | Fun - | Integer - | List - | Tuple - | Union - | UserDefined %% described in Section 2 + <pre> atom() | 'bar' | integer() | 42</pre> + <p> + describes the same set of terms as the type union: + </p> + <pre> atom() | integer()</pre> + <p> + Because of sub-type relations that exist between types, types + form a lattice where the topmost element, <c>any()</c>, denotes + the set of all Erlang terms and the bottom-most element, <c>none()</c>, + denotes the empty set of terms. + </p> + <p> + The set of predefined types and the syntax for types is given below: + </p> + <pre><![CDATA[ + Type :: any() %% The top type, the set of all Erlang terms + | none() %% The bottom type, contains no terms + | pid() + | port() + | reference() + | [] %% nil + | Atom + | Bitstring + | float() + | Fun + | Integer + | List + | Tuple + | Union + | UserDefined %% described in Section 6.3 -Union :: Type1 | Type2 + Atom :: atom() + | Erlang_Atom %% 'foo', 'bar', ... -Atom :: atom() - | Erlang_Atom %% 'foo', 'bar', ... + Bitstring :: <<>> + | <<_:M>> %% M is a positive integer + | <<_:_*N>> %% N is a positive integer + | <<_:M, _:_*N>> -Binary :: binary() %% <<_:_ * 8>> - | <<>> - | <<_:Erlang_Integer>> %% Base size - | <<_:_*Erlang_Integer>> %% Unit size - | <<_:Erlang_Integer, _:_*Erlang_Integer>> + Fun :: fun() %% any function + | fun((...) -> Type) %% any arity, returning Type + | fun(() -> Type) + | fun((TList) -> Type) -Fun :: fun() %% any function - | fun((...) -> Type) %% any arity, returning Type - | fun(() -> Type) - | fun((TList) -> Type) + Integer :: integer() + | Erlang_Integer %% ..., -1, 0, 1, ... 42 ... + | Erlang_Integer..Erlang_Integer %% specifies an integer range -Integer :: integer() - | Erlang_Integer %% ..., -1, 0, 1, ... 42 ... - | Erlang_Integer..Erlang_Integer %% specifies an integer range + List :: list(Type) %% Proper list ([]-terminated) + | improper_list(Type1, Type2) %% Type1=contents, Type2=termination + | maybe_improper_list(Type1, Type2) %% Type1 and Type2 as above -List :: list(Type) %% Proper list ([]-terminated) - | improper_list(Type1, Type2) %% Type1=contents, Type2=termination - | maybe_improper_list(Type1, Type2) %% Type1 and Type2 as above + Tuple :: tuple() %% stands for a tuple of any size + | {} + | {TList} -Tuple :: tuple() %% stands for a tuple of any size - | {} - | {TList} + TList :: Type + | Type, TList -TList :: Type - | Type, TList + Union :: Type1 | Type2 ]]></pre> <p> + The general form of bitstrings is <c><<_:M, _:_*N>></c>, + where <c>M</c> and <c>N</c> are positive integers. It denotes a + bitstring that is <c>M + (k*N)</c> bits long (i.e., a bitstring that + starts with <c>M</c> bits and continues with <c>k</c> segments of + <c>N</c> bits each, where <c>k</c> is also a positive integer). + The notations <c><<_:_*N>></c>, <c><<_:M>></c>, + and <c><<>></c> are convenient shorthands for the cases + that <c>M</c>, <c>N</c>, or both, respectively, are zero. + </p> + <p> Because lists are commonly used, they have shorthand type notations. The type <c>list(T)</c> has the shorthand <c>[T]</c>. The shorthand <c>[T,...]</c> stands for @@ -154,11 +164,17 @@ TList :: Type </p> <table> <row> - <cell><b>Built-in type</b></cell><cell><b>Stands for</b></cell> + <cell><b>Built-in type</b></cell><cell><b>Defined as</b></cell> </row> <row> <cell><c>term()</c></cell><cell><c>any()</c></cell> </row> + <row> + <cell><c>binary()</c></cell><cell><c><<_:*8>></c></cell> + </row> + <row> + <cell><c>bitstring()</c></cell><cell><c><<_:*1>></c></cell> + </row> <row> <cell><c>boolean()</c></cell><cell><c>'false' | 'true'</c></cell> </row> @@ -169,15 +185,6 @@ TList :: Type <cell><c>char()</c></cell><cell><c>0..16#10ffff</c></cell> </row> <row> - <cell><c>non_neg_integer()</c></cell><cell><c>0..</c></cell> - </row> - <row> - <cell><c>pos_integer()</c></cell><cell><c>1..</c></cell> - </row> - <row> - <cell><c>neg_integer()</c></cell><cell><c>..-1</c></cell> - </row> - <row> <cell><c>number()</c></cell><cell><c>integer() | float()</c></cell> </row> <row> @@ -196,7 +203,7 @@ TList :: Type <cell><c>nonempty_string()</c></cell><cell><c>[char(),...]</c></cell> </row> <row> - <cell><c>iolist()</c></cell><cell><c>maybe_improper_list(char() | binary() | iolist(), binary() | [])</c></cell> + <cell><c>iolist()</c></cell><cell><c>maybe_improper_list(byte() | binary() | iolist(), binary() | [])</c></cell> </row> <row> <cell><c>module()</c></cell><cell><c>atom()</c></cell> @@ -214,35 +221,54 @@ TList :: Type <cell><c>no_return()</c></cell><cell><c>none()</c></cell> </row> </table> + <p> + In addition, the following three built-in types exist and can be + thought as defined below, though strictly their "type definition" is + not valid syntax according to the type language defined above. + </p> + <table> + <row> + <cell><b>Built-in type</b></cell><cell><b>Could be thought defined by the syntax</b></cell> + </row> + <row> + <cell><c>non_neg_integer()</c></cell><cell><c>0..</c></cell> + </row> + <row> + <cell><c>pos_integer()</c></cell><cell><c>1..</c></cell> + </row> + <row> + <cell><c>neg_integer()</c></cell><cell><c>..-1</c></cell> + </row> + </table> <p> Users are not allowed to define types with the same names as the predefined or built-in ones. This is checked by the compiler and its violation results in a compilation error. - (For bootstrapping purposes, it can also result to just a warning if this - involves a built-in type which has just been introduced.) + (For bootstrapping purposes, it can also result to just a warning + if this involves a built-in type which has just been introduced.) </p> <note> The following built-in list types also exist, but they are expected to be rarely used. Hence, they have long names: </note> <pre> -nonempty_maybe_improper_list(Type) :: nonempty_maybe_improper_list(Type, any()) -nonempty_maybe_improper_list() :: nonempty_maybe_improper_list(any())</pre> + nonempty_maybe_improper_list(Type) :: nonempty_maybe_improper_list(Type, any()) + nonempty_maybe_improper_list() :: nonempty_maybe_improper_list(any())</pre> <p> where the following two types define the set of Erlang terms one would expect: </p> <pre> -nonempty_improper_list(Type1, Type2) -nonempty_maybe_improper_list(Type1, Type2)</pre> + nonempty_improper_list(Type1, Type2) + nonempty_maybe_improper_list(Type1, Type2)</pre> <p> Also for convenience, we allow for record notation to be used. Records are just shorthands for the corresponding tuples. </p> <pre> -Record :: #Erlang_Atom{} - | #Erlang_Atom{Fields}</pre> + Record :: #Erlang_Atom{} + | #Erlang_Atom{Fields}</pre> <p> Records have been extended to possibly contain type information. This is described in the sub-section <seealso marker="#typeinrecords">"Type information in record declarations"</seealso> below. @@ -257,8 +283,8 @@ Record :: #Erlang_Atom{} compiler attributes as in the following: </p> <pre> --type my_struct_type() :: Type. --opaque my_opaq_type() :: Type.</pre> + -type my_struct_type() :: Type. + -opaque my_opaq_type() :: Type.</pre> <p> where the type name is an atom (<c>'my_struct_type'</c> in the above) followed by parentheses. Type is a type as defined in the @@ -279,23 +305,23 @@ Record :: #Erlang_Atom{} definition. A concrete example appears below: </p> <pre> --type orddict(Key, Val) :: [{Key, Val}].</pre> + -type orddict(Key, Val) :: [{Key, Val}].</pre> <p> A module can export some types in order to declare that other modules are allowed to refer to them as <em>remote types</em>. This declaration has the following form: <pre> --export_type([T1/A1, ..., Tk/Ak]).</pre> + -export_type([T1/A1, ..., Tk/Ak]).</pre> where the Ti's are atoms (the name of the type) and the Ai's are their arguments. An example is given below: <pre> --export_type([my_struct_type/0, orddict/2]).</pre> + -export_type([my_struct_type/0, orddict/2]).</pre> Assuming that these types are exported from module <c>'mod'</c> then one can refer to them from other modules using remote type expressions like those below: <pre> -mod:my_struct_type() -mod:orddict(atom(), term())</pre> + mod:my_struct_type() + mod:orddict(atom(), term())</pre> One is not allowed to refer to types which are not declared as exported. </p> <p> @@ -317,19 +343,19 @@ mod:orddict(atom(), term())</pre> record. The syntax for this is: </p> <pre> --record(rec, {field1 :: Type1, field2, field3 :: Type3}).</pre> + -record(rec, {field1 :: Type1, field2, field3 :: Type3}).</pre> <p> For fields without type annotations, their type defaults to any(). I.e., the above is a shorthand for: </p> <pre> --record(rec, {field1 :: Type1, field2 :: any(), field3 :: Type3}).</pre> + -record(rec, {field1 :: Type1, field2 :: any(), field3 :: Type3}).</pre> <p> In the presence of initial values for fields, the type must be declared after the initialization as in the following: </p> <pre> --record(rec, {field1 = [] :: Type1, field2, field3 = 42 :: Type3}).</pre> + -record(rec, {field1 = [] :: Type1, field2, field3 = 42 :: Type3}).</pre> <p> Naturally, the initial values for fields should be compatible with (i.e. a member of) the corresponding types. @@ -340,13 +366,13 @@ mod:orddict(atom(), term())</pre> effects: </p> <pre> --record(rec, {f1 = 42 :: integer(), - f2 :: float(), - f3 :: 'a' | 'b'}). + -record(rec, {f1 = 42 :: integer(), + f2 :: float(), + f3 :: 'a' | 'b'}). --record(rec, {f1 = 42 :: integer(), - f2 :: 'undefined' | float(), - f3 :: 'undefined' | 'a' | 'b'}).</pre> + -record(rec, {f1 = 42 :: integer(), + f2 :: 'undefined' | float(), + f3 :: 'undefined' | 'a' | 'b'}).</pre> <p> For this reason, it is recommended that records contain initializers, whenever possible. @@ -355,15 +381,13 @@ mod:orddict(atom(), term())</pre> Any record, containing type information or not, once defined, can be used as a type using the syntax: </p> - <pre> -#rec{}</pre> + <pre> #rec{}</pre> <p> In addition, the record fields can be further specified when using a record type by adding type information about the field in the following manner: </p> - <pre> -#rec{some_field :: Type}</pre> + <pre> #rec{some_field :: Type}</pre> <p> Any unspecified fields are assumed to have the type in the original record declaration. @@ -377,7 +401,7 @@ mod:orddict(atom(), term())</pre> compiler attribute <c>'-spec'</c>. The general format is as follows: </p> <pre> --spec Module:Function(ArgType1, ..., ArgTypeN) -> ReturnType.</pre> + -spec Module:Function(ArgType1, ..., ArgTypeN) -> ReturnType.</pre> <p> The arity of the function has to match the number of arguments, or else a compilation error occurs. @@ -392,19 +416,19 @@ mod:orddict(atom(), term())</pre> For most uses within a given module, the following shorthand suffices: </p> <pre> --spec Function(ArgType1, ..., ArgTypeN) -> ReturnType.</pre> + -spec Function(ArgType1, ..., ArgTypeN) -> ReturnType.</pre> <p> Also, for documentation purposes, argument names can be given: </p> <pre> --spec Function(ArgName1 :: Type1, ..., ArgNameN :: TypeN) -> RT.</pre> + -spec Function(ArgName1 :: Type1, ..., ArgNameN :: TypeN) -> RT.</pre> <p> A function specification can be overloaded. That is, it can have several types, separated by a semicolon (<c>;</c>): </p> <pre> --spec foo(T1, T2) -> T3 - ; (T4, T5) -> T6.</pre> + -spec foo(T1, T2) -> T3 + ; (T4, T5) -> T6.</pre> <p> A current restriction, which currently results in a warning (OBS: not an error) by the compiler, is that the domains of @@ -412,8 +436,8 @@ mod:orddict(atom(), term())</pre> For example, the following specification results in a warning: </p> <pre> --spec foo(pos_integer()) -> pos_integer() - ; (integer()) -> integer().</pre> + -spec foo(pos_integer()) -> pos_integer() + ; (integer()) -> integer().</pre> <p> Type variables can be used in specifications to specify relations for the input and output arguments of a function. @@ -421,47 +445,66 @@ mod:orddict(atom(), term())</pre> polymorphic identity function: </p> <pre> --spec id(X) -> X.</pre> + -spec id(X) -> X.</pre> <p> However, note that the above specification does not restrict the input and output type in any way. - We can constrain these types by guard-like subtype constraints: + We can constrain these types by guard-like subtype constraints + and provide bounded quantification: </p> - <pre> --spec id(X) -> X when is_subtype(X, tuple()).</pre> + <pre> -spec id(X) -> X when X :: tuple().</pre> <p> - or equivalently by the more succinct and more modern form of the above: - </p> - <pre> --spec id(X) -> X when X :: tuple().</pre> - <p> - and provide bounded quantification. Currently, the <c>::</c> constraint - (the <c>is_subtype/2</c> guard) is the only guard constraint which can - be used in the <c>'when'</c> part of a <c>'-spec'</c> attribute. + Currently, the <c>::</c> constraint (read as <c>is_subtype</c>) is + the only guard constraint which can be used in the <c>'when'</c> + part of a <c>'-spec'</c> attribute. </p> + <note> + <p> + The above function specification, using multiple occurrences of + the same type variable, provides more type information than the + function specification below where the type variables are missing: + </p> + <pre> -spec id(tuple()) -> tuple().</pre> + <p> + The latter specification says that the function takes some tuple + and returns some tuple, while the one with the <c>X</c> type + variable specifies that the function takes a tuple and returns + <em>the same</em> tuple. + </p> + <p> + However, it's up to the tools that process the specs to choose + whether to take this extra information into account or ignore it. + </p> + </note> <p> The scope of an <c>::</c> constraint is the <c>(...) -> RetType</c> specification after which it appears. To avoid confusion, we suggest that different variables are used in different - constituents of an overloaded contract as in the example below: + constituents of an overloaded contract as in the example below: </p> <pre> --spec foo({X, integer()}) -> X when X :: atom() - ; ([Y]) -> Y when Y :: number().</pre> + -spec foo({X, integer()}) -> X when X :: atom() + ; ([Y]) -> Y when Y :: number().</pre> + <note> + For backwards compatibility the following form is also allowed: + <pre> -spec id(X) -> X when is_subtype(X, tuple()).</pre> + <p> + but its use is discouraged. It will be taken out in a future + Erlang/OTP release. + </p> + </note> <p> Some functions in Erlang are not meant to return; either because they define servers or because they are used to throw exceptions as the function below: </p> - <pre> -my_error(Err) -> erlang:throw({error, Err}).</pre> + <pre> my_error(Err) -> erlang:throw({error, Err}).</pre> <p> - For such functions we recommend the use of the special no_return() + For such functions we recommend the use of the special <c>no_return()</c> type for their "return", via a contract of the form: </p> - <pre> --spec my_error(term()) -> no_return().</pre> + <pre> -spec my_error(term()) -> no_return().</pre> </section> </chapter> diff --git a/system/doc/top/Makefile b/system/doc/top/Makefile index 673ba44c94..37466fa2d9 100644 --- a/system/doc/top/Makefile +++ b/system/doc/top/Makefile @@ -1,7 +1,7 @@ # # %CopyrightBegin% # -# Copyright Ericsson AB 1999-2012. All Rights Reserved. +# Copyright Ericsson AB 1999-2013. All Rights Reserved. # # The contents of this file are subject to the Erlang Public License, # Version 1.1, (the "License"); you may not use this file except in @@ -162,7 +162,7 @@ $(MAN_INDEX): $(MAN_INDEX_SCRIPT) #-------------------------------------------------------------------------- $(HTMLDIR)/highlights.html: highlights.xml - date=`date +"%B %e %Y"`; \ + date=`date +"%B %e, %Y"`; \ $(XSLTPROC) --output $(@) \ --stringparam docgen "$(DOCGEN)" \ --stringparam topdocdir "$(TOPDOCDIR)" \ @@ -179,7 +179,7 @@ $(HTMLDIR)/highlights.html: highlights.xml $(HTMLDIR)/incompatible.html: incompatible.xml - date=`date +"%B %e %Y"`; \ + date=`date +"%B %e, %Y"`; \ $(XSLTPROC) --output $(@) --stringparam docgen "$(DOCGEN)" \ --stringparam topdocdir "$(TOPDOCDIR)" \ --stringparam pdfdir "$(PDFREFDIR)" \ |