diff options
Diffstat (limited to 'erts/doc/src/erlang.xml')
| -rw-r--r-- | erts/doc/src/erlang.xml | 319 |
1 files changed, 228 insertions, 91 deletions
diff --git a/erts/doc/src/erlang.xml b/erts/doc/src/erlang.xml index 46f8df4683..1eec45e0f3 100644 --- a/erts/doc/src/erlang.xml +++ b/erts/doc/src/erlang.xml @@ -253,6 +253,54 @@ iolist() = [char() | binary() | iolist()] </desc> </func> <func> + <name>binary_part(Subject, PosLen) -> binary()</name> + <fsummary>Extracts a part of a binary</fsummary> + <type> + <v>Subject = binary()</v> + <v>PosLen = {Start,Length}</v> + <v>Start = int()</v> + <v>Length = int()</v> + </type> + <desc> + <p>Extracts the part of the binary described by <c>PosLen</c>.</p> + + <p>Negative length can be used to extract bytes at the end of a binary:</p> + +<code> +1> Bin = <<1,2,3,4,5,6,7,8,9,10>>. +2> binary_part(Bin,{byte_size(Bin), -5)). +<<6,7,8,9,10>> +</code> + + <p>If <c>PosLen</c> in any way references outside the binary, a <c>badarg</c> exception is raised.</p> + + <p><c>Start</c> is zero-based, i.e:</p> +<code> +1> Bin = <<1,2,3>> +2> binary_part(Bin,{0,2}). +<<1,2>> +</code> + + <p>See the STDLIB module <c>binary</c> for details about the <c>PosLen</c> semantics.</p> + + <p>Allowed in guard tests.</p> + </desc> + </func> + <func> + <name>binary_part(Subject, Start, Length) -> binary()</name> + <fsummary>Extracts a part of a binary</fsummary> + <type> + <v>Subject = binary()</v> + <v>Start = int()</v> + <v>Length = int()</v> + </type> + <desc> + <p>The same as <c>binary_part(Subject, {Pos, Len})</c>.</p> + + <p>Allowed in guard tests.</p> + </desc> + </func> + <func> <name>binary_to_atom(Binary, Encoding) -> atom()</name> <fsummary>Convert from text representation to an atom</fsummary> <type> @@ -318,6 +366,11 @@ iolist() = [char() | binary() | iolist()] corresponding to the bytes from position <c>Start</c> to position <c>Stop</c> in <c>Binary</c>. Positions in the binary are numbered starting from 1.</p> + + <note><p>This function's indexing style of using one-based indices for + binaries is deprecated. New code should use the functions in + the STDLIB module <c>binary</c> instead. They consequently + use the same (zero-based) style of indexing.</p></note> </desc> </func> <func> @@ -354,7 +407,7 @@ iolist() = [char() | binary() | iolist()] </desc> </func> <func> - <name>erlang:binary_to_term(Binary, Opts) -> term()</name> + <name>binary_to_term(Binary, Opts) -> term()</name> <fsummary>Decode an Erlang external term format binary</fsummary> <type> <v>Opts = [safe]</v> @@ -446,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> @@ -710,7 +763,7 @@ false</pre> <name>erlang: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 @@ -750,7 +803,7 @@ false</pre> <name>erlang: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> @@ -2107,7 +2160,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> @@ -2156,7 +2209,7 @@ os_prompt%</pre> </desc> </func> <func> - <name>erlang:max(Term1, Term2) -> Maximum</name> + <name>max(Term1, Term2) -> Maximum</name> <fsummary>Return the largest of two term</fsummary> <type> <v>Term1 = Term2 = Maximum = term()</v> @@ -2405,7 +2458,7 @@ os_prompt%</pre> </desc> </func> <func> - <name>erlang:min(Term1, Term2) -> Minimum</name> + <name>min(Term1, Term2) -> Minimum</name> <fsummary>Return the smallest of two term</fsummary> <type> <v>Term1 = Term2 = Minimum = term()</v> @@ -2591,6 +2644,37 @@ os_prompt%</pre> </desc> </func> <func> + <name>erlang:nif_error(Reason)</name> + <fsummary>Stop execution with a given reason</fsummary> + <type> + <v>Reason = term()</v> + </type> + <desc> + <p>Works exactly like + <seealso marker="#error/1">erlang:error/1</seealso>, + but Dialyzer thinks that this BIF will return an arbitrary term. + When used in a stub function for a NIF to generate an + exception when the NIF library is not loaded, Dialyzer + will not generate false warnings.</p> + </desc> + </func> + <func> + <name>erlang:nif_error(Reason, Args)</name> + <fsummary>Stop execution with a given reason</fsummary> + <type> + <v>Reason = term()</v> + <v>Args = [term()]</v> + </type> + <desc> + <p>Works exactly like + <seealso marker="#error/2">erlang:error/2</seealso>, + but Dialyzer thinks that this BIF will return an arbitrary term. + When used in a stub function for a NIF to generate an + exception when the NIF library is not loaded, Dialyzer + will not generate false warnings.</p> + </desc> + </func> + <func> <name>node() -> Node</name> <fsummary>Name of the local node</fsummary> <type> @@ -2606,7 +2690,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> @@ -2683,8 +2767,10 @@ os_prompt%</pre> Otherwise, some other point in time is chosen. It is also guaranteed that subsequent calls to this BIF returns continuously increasing values. Hence, the return value from - <c>now()</c> can be used to generate unique time-stamps. It - can only be used to check the local time of day if + <c>now()</c> can be used to generate unique time-stamps, + and if it is called in a tight loop on a fast machine + the time of the node can become skewed.</p> + <p>It can only be used to check the local time of day if the time-zone info of the underlying operating system is properly configured.</p> </desc> @@ -2749,7 +2835,7 @@ os_prompt%</pre> <item> <p>Works like <c>{spawn, Command}</c>, but only runs - external executables. The <c>Command</c> in it's whole + external executables. The <c>Command</c> in its whole is used as the name of the executable, including any spaces. If arguments are to be passed, the <c>args</c> and <c>arg0</c> <c>PortSettings</c> can be used.</p> @@ -2926,7 +3012,7 @@ os_prompt%</pre> The standard input and standard output handles of the port program will, if this option is supplied, be opened with the flag FILE_FLAG_OVERLAPPED, so that the port program can (and has to) do - overlapped I/O on it's standard handles. This is not normally + overlapped I/O on its standard handles. This is not normally the case for simple port programs, but an option of value for the experienced Windows programmer. <em>On all other platforms, this option is silently discarded</em>.</p> @@ -3147,7 +3233,7 @@ os_prompt%</pre> </desc> </func> <func> - <name>erlang:port_command(Port, Data, OptionList) -> true|false</name> + <name>port_command(Port, Data, OptionList) -> true|false</name> <fsummary>Send data to a port</fsummary> <type> <v>Port = port() | atom()</v> @@ -3183,10 +3269,6 @@ os_prompt%</pre> <note> <p>More options may be added in the future.</p> </note> - <note> - <p><c>erlang:port_command/3</c> is currently not auto imported, but - it is planned to be auto imported in OTP R14.</p> - </note> <p>Failures:</p> <taglist> <tag><c>badarg</c></tag> @@ -4016,7 +4098,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 @@ -4039,7 +4121,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 @@ -4218,7 +4300,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> @@ -4431,7 +4513,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> @@ -4747,7 +4829,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 @@ -5093,9 +5175,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, 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 @@ -5103,10 +5185,21 @@ true</pre> For more information on how to define the CPU topology, see <seealso marker="#system_flag_cpu_topology">erlang:system_flag(cpu_topology, CpuTopology)</seealso>. </p> - <p><em>NOTE:</em> If other programs on the system have bound - to processors, e.g. another Erlang runtime system, you - may loose performance when binding schedulers. Therefore, - schedulers are by default not bound.</p> + <p>The runtime system will by default bind schedulers to logical + processors using the <c>default_bind</c> bind type if the amount + of schedulers are 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><em>NOTE:</em> If the Erlang runtime system is the only + operating system process that binds threads to logical processors, + this improves the performance of the runtime system. However, + if other operating system processes (as for example another Erlang + runtime system) also bind threads to logical processors, there + might be a performance penalty instead. If this is the case you, + are are advised to unbind the schedulers using the + <seealso marker="erl#+sbt">+sbtu</seealso> command line argument, + or <c>erlang:system_flag(scheduler_bind_type, unbound)</c>.</p> <p>Schedulers can be bound in different ways. The <c>How</c> argument determines how schedulers are bound. <c>How</c> can currently be one of:</p> @@ -5271,7 +5364,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> @@ -5286,7 +5379,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 @@ -5440,7 +5533,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 @@ -5450,12 +5543,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, 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> @@ -5513,52 +5608,9 @@ 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><c>fullsweep_after</c></tag> <item> @@ -5634,11 +5686,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 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 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 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> @@ -5843,6 +5918,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 @@ -5850,9 +5945,23 @@ true</pre> </item> <tag><c>wordsize</c></tag> <item> - <p>Returns the word size in bytes as an integer, i.e. on a - 32-bit architecture 4 is returned, and on a 64-bit - architecture 8 is returned.</p> + <p>Same as <c>{wordsize, internal}</c></p> + </item> + <tag><c>{wordsize, internal}</c></tag> + <item> + <p>Returns the size of Erlang term words in bytes as an + integer, i.e. on a 32-bit architecture 4 is returned, + and on a pure 64-bit architecture 8 is returned. On a + halfword 64-bit emulator, 4 is returned, as the Erlang + terms are stored using a virtual wordsize of half the + systems wordsize.</p> + </item> + <tag><c>{wordsize, external}</c></tag> + <item> + <p>Returns the true wordsize of the emulator, i.e. the size + of a pointer, in bytes as an integer. On a pure 32-bit + architecture 4 is returned, on both a halfword and pure + 64-bit architecture, 8 is returned.</p> </item> </taglist> <note> @@ -6645,6 +6754,17 @@ true</pre> See also <seealso marker="#trace_pattern/3">erlang:trace_pattern/3</seealso>.</p> </item> + <tag><c>call_time</c></tag> + <item> + <p>Return the call time values for this function or + <c>true</c> for the pseudo function <c>on_load</c> if call + time tracing is active. Returns <c>false</c> otherwise. + The call time values returned, <c>[{Pid, Count, S, Us}]</c>, + is a list of each process that has executed the function and its specific counters. + See also + <seealso marker="#trace_pattern/3">erlang:trace_pattern/3</seealso>.</p> + </item> + <tag><c>all</c></tag> <item> <p>Return a list containing the <c>{Item, Value}</c> tuples @@ -6747,13 +6867,13 @@ true</pre> </item> <tag><c>restart</c></tag> <item> - <p>For the <c>FlagList</c> option <c>call_count</c>: + <p>For the <c>FlagList</c> option <c>call_count</c> and <c>call_time</c>: restart the existing counters. The behaviour is undefined for other <c>FlagList</c> options.</p> </item> <tag><c>pause</c></tag> <item> - <p>For the <c>FlagList</c> option <c>call_count</c>: pause + <p>For the <c>FlagList</c> option <c>call_count</c> and <c>call_time</c>: pause the existing counters. The behaviour is undefined for other <c>FlagList</c> options.</p> </item> @@ -6808,6 +6928,23 @@ true</pre> <p>The counter value can be read with <seealso marker="#trace_info/2">erlang:trace_info/2</seealso>.</p> </item> + <tag><c>call_time</c></tag> + <item> + <p>Starts (<c>MatchSpec == true</c>) or stops + (<c>MatchSpec == false</c>) call time tracing for all + types of function calls. For every function a counter is + incremented when the function is called. Time spent in the function + is accumulated in two other counters, seconds and micro-seconds. + The counters are stored for each call traced process.</p> + <p>If call time tracing is started while already running, + the count and time is restarted from zero. Running counters can be + paused with <c>MatchSpec == pause</c>. Paused and running + counters can be restarted from zero with + <c>MatchSpec == restart</c>.</p> + <p>The counter value can be read with + <seealso marker="#trace_info/2">erlang:trace_info/2</seealso>.</p> + </item> + </taglist> <p>The <c>global</c> and <c>local</c> options are mutually exclusive and <c>global</c> is the default (if no options are @@ -6815,7 +6952,7 @@ true</pre> perform a kind of local tracing, and can also not be combined with <c>global</c>. A function can be either globally or locally traced. If global tracing is specified for a - specified set of functions; local, meta and call count + specified set of functions; local, meta, call time and call count tracing for the matching set of local functions will be disabled, and vice versa.</p> <p>When disabling trace, the option must match the type of trace |