diff options
Diffstat (limited to 'erts/doc/src/erlang.xml')
| -rw-r--r-- | erts/doc/src/erlang.xml | 250 |
1 files changed, 171 insertions, 79 deletions
diff --git a/erts/doc/src/erlang.xml b/erts/doc/src/erlang.xml index 46f8df4683..579a5a14c6 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> @@ -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 @@ -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 @@ -5513,52 +5606,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> @@ -5850,9 +5900,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 +6709,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 +6822,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 +6883,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 +6907,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 |