From 3aa27a437b27d2c02357ed28360b67e3005e49d3 Mon Sep 17 00:00:00 2001 From: Lukas Larsson Date: Thu, 1 Mar 2018 16:10:45 +0100 Subject: erts: Cleanup erlang:system_info docs Attempt to make the system_info docs easier to navigate by grouping items of similar themes together in the documentation. --- erts/doc/src/erlang.xml | 1840 +++++++++++++++++++++++------------------ erts/doc/src/notes.xml | 2 +- erts/preloaded/src/erlang.erl | 9 +- 3 files changed, 1062 insertions(+), 789 deletions(-) diff --git a/erts/doc/src/erlang.xml b/erts/doc/src/erlang.xml index 771897ba94..56eaa47af4 100644 --- a/erts/doc/src/erlang.xml +++ b/erts/doc/src/erlang.xml @@ -6753,17 +6753,20 @@ lists:map( be included in the result. That is, all scheduler threads that are expected to handle CPU bound work. If you also want information about dirty I/O schedulers, use - statistics(scheduler_wall_time_all) + + statistics(scheduler_wall_time_all) instead.

Normal schedulers will have scheduler identifiers in the range 1 =< SchedulerId =< - erlang:system_info(schedulers). + + erlang:system_info(schedulers). Dirty CPU schedulers will have scheduler identifiers in the range erlang:system_info(schedulers) < SchedulerId =< erlang:system_info(schedulers) + - erlang:system_info(dirty_cpu_schedulers). + + erlang:system_info(dirty_cpu_schedulers).

The different types of schedulers handle specific types of jobs. Every job is assigned to a specific @@ -6839,13 +6842,16 @@ ok schedulers.

Dirty IO schedulers will have scheduler identifiers in the range - erlang:system_info(schedulers) + + erlang:system_info(schedulers) + - erlang:system_info(dirty_cpu_schedulers) < + + erlang:system_info(dirty_cpu_schedulers) < SchedulerId =< erlang:system_info(schedulers) + erlang:system_info(dirty_cpu_schedulers) + - erlang:system_info(dirty_io_schedulers).

+ + erlang:system_info(dirty_io_schedulers).

Note that work executing on dirty I/O schedulers are expected to mainly wait for I/O. That is, when you get high scheduler utilization on dirty I/O schedulers, @@ -7484,11 +7490,144 @@ ok - - - - - + + System info overview. + +

Returns information about the current system. + The documentation of this function is broken into the following + sections in order to make it easier to navigate.

+ + + Memory Allocation + +

+ allocated_areas, + allocator, + alloc_util_allocators, + allocator_sizes, + elib_malloc +

+ + + CPU Topology + +

+ cpu_topology, + logical_processors, + update_cpu_info +

+ + + Process Information + +

+ fullsweep_after, + garbage_collection, + heap_sizes, + heap_type, + max_heap_size, + message_queue_data, + min_heap_size, + min_bin_vheap_size, + procs +

+ + + System Limits + +

+ atom_count, + atom_limit, + ets_limit, + port_count, + port_limit, + process_count, + process_limit +

+ + + System Time + +

+ end_time, + os_monotonic_time_source, + os_system_time_source, + start_time, + time_correction, + time_offset, + time_warp_mode, + tolerant_timeofday +

+ + + Scheduler Information + +

+ dirty_cpu_schedulers, + dirty_cpu_schedulers_online, + dirty_io_schedulers, + multi_scheduling, + multi_scheduling_blockers, + normal_multi_scheduling_blockers, + scheduler_bind_type, + scheduler_bindings, + scheduler_id, + schedulers, + smp_support, + threads, + thread_pool_size +

+ + + Distribution Information + +

+ creation, + delayed_node_table_gc, + dist, + dist_buf_busy_limit, + dist_ctrl +

+ + + System Information + +

+ build_type, + c_compiler_used, + check_io, + compat_rel, + debug_compiled, + driver_version, + dynamic_trace, + dynamic_trace_probes, + info, + kernel_poll, + loaded, + machine, + modified_timing_level, + nif_version, + otp_release, + port_parallelism, + system_version, + system_architecture, + trace_control_word, + version, + wordsize +

+ + + + + + + + + + + + Information about the system allocators. @@ -7497,12 +7636,13 @@ ok -

Returns various information about the allocators of the - current system (emulator) as specified by +

Returns various information about the memory allocators + of the current system (emulator) as specified by Item:

- allocated_areas + + allocated_areas

Returns a list of tuples with information about miscellaneous allocated memory areas.

@@ -7524,9 +7664,9 @@ ok erlang:memory/0,1.

 - allocator + + allocator -

Returns {Allocator, Version, Features, Settings, where:

@@ -7559,19 +7699,9 @@ ok erts_alloc(3).

 - alloc_util_allocators - - -

Returns a list of the names of all allocators using - the ERTS internal alloc_util framework - as atoms. For more information, see section - The - alloc_util framework - in erts_alloc(3).

- - {allocator, Alloc} + + {allocator, Alloc} -

Returns information about the specified allocator. As from ERTS 5.6.1, the return value is a list of {instance, InstanceNo, InstanceInfo} tuples, @@ -7616,9 +7746,19 @@ ok values. The first value is the memory pool size and the second value is the used memory size.

 - {allocator_sizes, Alloc} + + alloc_util_allocators + +

Returns a list of the names of all allocators using + the ERTS internal alloc_util framework + as atoms. For more information, see section + The + alloc_util framework + in erts_alloc(3).

+ + + {allocator_sizes, Alloc} -

Returns various size information for the specified allocator. The information returned is a subset of the information returned by @@ -7626,14 +7766,23 @@ ok erlang:system_info({allocator, Alloc}).

 + + elib_malloc + +

This option will be removed in a future release. + The return value will always be false, as the + elib_malloc allocator has been removed.

+ - + anchor="system_info_cpu_topology"/> + + + Information about the CPU topology of the system. @@ -7664,7 +7813,8 @@ ok the current system (emulator) as specified by Item:

- cpu_topology + + cpu_topology

Returns the CpuTopology currently used by the emulator. The CPU topology is used when binding schedulers @@ -7727,31 +7877,89 @@ ok cpu_topology.

 + + logical_processors + +

Returns the detected number of logical processors configured + in the system. The return value is either an integer, or + the atom unknown if the emulator cannot + detect the configured logical processors.

+ + + logical_processors_available + +

Returns the detected number of logical processors available + to the Erlang runtime system. The return value is either an + integer, or the atom unknown if the emulator + cannot detect the available logical processors. The number + of available logical processors is less than or equal to + the number of + logical processors online.

+ + + logical_processors_online + +

Returns the detected number of logical processors online on + the system. The return value is either an integer, + or the atom unknown if the emulator cannot + detect logical processors online. The number of logical + processors online is less than or equal to the number of + logical processors + configured.

+ + + update_cpu_info + +

The runtime system rereads the CPU information available + and updates its internally stored information about the + detected + CPU topology and the number of logical processors + configured, + online, + and + available.

+

If the CPU information has changed since the last time + it was read, the atom changed is returned, otherwise + the atom unchanged. If the CPU information has changed, + you probably want to + adjust the + number of schedulers online. You typically want + to have as many schedulers online as + logical + processors available.

+ - - - - - - + + + + + + + + + Information about the default process heap settings. +

Returns information about the default process heap settings:

- fullsweep_after + + fullsweep_after

Returns {fullsweep_after, integer() >= 0}, which is the fullsweep_after garbage collection setting used by default. For more information, see garbage_collection described below.

 - garbage_collection + + garbage_collection

Returns a list describing the default garbage collection settings. A process spawned on the local node by a @@ -7764,7 +7972,30 @@ ok can spawn a process that does not use the default settings.

 - max_heap_size + + heap_sizes + +

Returns a list of integers representing valid heap sizes + in words. All Erlang heaps are sized from sizes in this + list.

+ + + heap_type + +

Returns the heap type used by the current emulator. One + heap type exists:

+ + private + + Each process has a heap reserved for its use and no + references between heaps of different processes are + allowed. Messages passed between processes are copied + between heaps. + + + + + max_heap_size

Returns {max_heap_size, MaxHeapSize}, where MaxHeapSize is the current @@ -7792,185 +8023,376 @@ ok process_flag(message_queue_data, MQD).

 - min_heap_size + + min_heap_size

Returns {min_heap_size, MinHeapSize}, where MinHeapSize is the current system-wide minimum heap size for spawned processes.

 - min_bin_vheap_size + + min_bin_vheap_size

Returns {min_bin_vheap_size, MinBinVHeapSize}, where MinBinVHeapSize is the current system-wide minimum binary virtual heap size for spawned processes.

 + + procs + +

Returns a binary containing a string of process and port + information formatted as in Erlang crash dumps. For more + information, see section + How to interpret the Erlang crash dumps + in the User's Guide.

+ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Information about the system. + + + + + + + + Information about various system limits. -

Returns various information about the current system - (emulator) as specified by Item:

+ +

Returns information about the current system + (emulator) limits as specified by Item:

- atom_count + + atom_count -

Returns the number of atoms currently existing at the - local node. The value is given as an integer.

+ local node. The value is given as an integer.

 - atom_limit + + atom_limit -

Returns the maximum number of atoms allowed. - This limit can be increased at startup by passing - command-line flag - +t to - erl(1). + This limit can be increased at startup by passing + command-line flag + +t to + erl(1).

- build_type + + ets_limit -

Returns an atom describing the build type of the runtime - system. This is normally the atom opt for optimized. - Other possible return values are debug, purify, - quantify, purecov, gcov, valgrind, - gprof, and lcnt. Possible return values - can be added or removed at any time without prior notice.

- - c_compiler_used - -

Returns a two-tuple describing the C compiler used when - compiling the runtime system. The first element is an - atom describing the name of the compiler, or undefined - if unknown. The second element is a term describing the - version of the compiler, or undefined if unknown.

+

Returns the maximum number of ETS tables allowed. This + limit can be increased at startup by passing + command-line flag + +e to + erl(1) or by setting environment variable + ERL_MAX_ETS_TABLES before starting the Erlang + runtime system.

 - check_io + port_count -

Returns a list containing miscellaneous information - about the emulators internal I/O checking. Notice that - the content of the returned list can vary between - platforms and over time. It is only guaranteed - that a list is returned.

+

Returns the number of ports currently existing at the + local node. The value is given as an integer. This is + the same value as returned by + length(erlang:ports()), but more efficient.

 - compat_rel + + port_limit -

Returns the compatibility mode of the local node as - an integer. The integer returned represents the - Erlang/OTP release that the current emulator has been - set to be backward compatible with. The compatibility - mode can be configured at startup by using command-line flag - +R in - erl(1).

+

Returns the maximum number of simultaneously existing + ports at the local node as an integer. This limit can be + configured at startup by using command-line flag + +Q in erl(1).

 - cpu_topology + + process_count -

See above.

+

Returns the number of processes currently existing at the + local node. The value is given as an integer. This is + the same value as returned by + length(processes()), but more efficient.

 - creation + + process_limit -

Returns the creation of the local node as an integer. - The creation is changed when a node is restarted. The - creation of a node is stored in process identifiers, port - identifiers, and references. This makes it (to some - extent) possible to distinguish between identifiers from - different incarnations of a node. The valid - creations are integers in the range 1..3, but this will - probably change in a future release. If the node is not - alive, 0 is returned.

+

Returns the maximum number of simultaneously existing + processes at the local node. The value is given as an + integer. This limit can be configured at startup by using + command-line flag +P + in erl(1).

 - debug_compiled + + + + + + + + + + + + + + Information about system time. + + +

Returns information about the current system + (emulator) time as specified by Item:

+ + end_time -

Returns true if the emulator has been - debug-compiled, otherwise false.

+

The last Erlang monotonic + time in native + time unit that + can be represented internally in the current Erlang runtime system + instance. The time between the + start time and + the end time is at least a quarter of a millennium.

 - delayed_node_table_gc + + os_monotonic_time_source - -

Returns the amount of time in seconds garbage collection - of an entry in a node table is delayed. This limit can be set - on startup by passing command-line flag - +zdntgc - to erl(1). For more information, see the documentation of - the command-line flag.

+

Returns a list containing information about the source of + OS + monotonic time that is used by the runtime system.

+

If [] is returned, no OS monotonic time is + available. The list contains two-tuples with Keys + as first element, and Values as second element. The + order of these tuples is undefined. The following + tuples can be part of the list, but more tuples can be + introduced in the future:

+ + {function, Function} +

Function is the name of the function + used. This tuple always exists if OS monotonic time is + available to the runtime system.

+ + {clock_id, ClockId} +

This tuple only exists if Function + can be used with different clocks. ClockId + corresponds to the clock identifier used when calling + Function.

+ + {resolution, OsMonotonicTimeResolution} +

Highest possible + + resolution + of current OS monotonic time source as parts per + second. If no resolution information can be retrieved + from the OS, OsMonotonicTimeResolution is + set to the resolution of the time unit of + Functions return value. That is, the actual + resolution can be lower than + OsMonotonicTimeResolution. Notice that + the resolution does not say anything about the + + accuracy or whether the + + precision aligns with the resolution. You do, + however, know that the precision is not better than + OsMonotonicTimeResolution.

+ + {extended, Extended} +

Extended equals yes if + the range of time values has been extended; + otherwise Extended equals no. The + range must be extended if Function + returns values that wrap fast. This typically + is the case when the return value is a 32-bit value.

+ + {parallel, Parallel} +

Parallel equals yes if + Function is called in parallel from multiple + threads. If it is not called in parallel, because + calls must be serialized, Parallel equals + no.

+ + {time, OsMonotonicTime} +

OsMonotonicTime equals current OS + monotonic time in native + time unit.

+ + - dirty_cpu_schedulers + + os_system_time_source - -

Returns the number of dirty CPU scheduler threads used by - the emulator. Dirty CPU schedulers execute CPU-bound - native functions, such as NIFs, linked-in driver code, - and BIFs that cannot be managed cleanly by the normal - emulator schedulers.

-

The number of dirty CPU scheduler threads is determined - at emulator boot time and cannot be changed after that. - However, the number of dirty CPU scheduler threads online - can be changed at any time. The number of dirty CPU - schedulers can be set at startup by passing - command-line flag - +SDcpu or +

Returns a list containing information about the source of + OS + system time that is used by the runtime system.

+

The list contains two-tuples with Keys + as first element, and Values as second element. The + order if these tuples is undefined. The following + tuples can be part of the list, but more tuples can be + introduced in the future:

+ + {function, Function} +

Function is the name of the funcion used.

+ + {clock_id, ClockId} +

Exists only if Function + can be used with different clocks. ClockId + corresponds to the clock identifier used when calling + Function.

+ + {resolution, OsSystemTimeResolution} +

Highest possible + + resolution + of current OS system time source as parts per + second. If no resolution information can be retrieved + from the OS, OsSystemTimeResolution is + set to the resolution of the time unit of + Functions return value. That is, the actual + resolution can be lower than + OsSystemTimeResolution. Notice that + the resolution does not say anything about the + + accuracy or whether the + + precision do align with the resolution. You do, + however, know that the precision is not better than + OsSystemTimeResolution.

+ + {parallel, Parallel} +

Parallel equals yes if + Function is called in parallel from multiple + threads. If it is not called in parallel, because + calls needs to be serialized, Parallel equals + no.

+ + {time, OsSystemTime} +

OsSystemTime equals current OS + system time in native + time unit.

+ + + + start_time + +

The Erlang monotonic + time in native + time unit at the + time when current Erlang runtime system instance started.

+

See also + erlang:system_info(end_time).

+ + + time_correction + +

Returns a boolean value indicating whether + + time correction is enabled or not.

+ + + time_offset + +

Returns the state of the time offset:

+ + preliminary + +

The time offset is preliminary, and will be changed + and finalized later. The preliminary time offset + is used during the preliminary phase of the + + single time warp mode.

+ + final + +

The time offset is final. This either because + + no time warp mode is used, or because the time + offset have been finalized when + + single time warp mode is used.

+ + volatile + +

The time offset is volatile. That is, it can + change at any time. This is because + + multi-time warp mode is used.

+ + + + + time_warp_mode + +

Returns a value identifying the + + time warp mode that is used:

+ + no_time_warp + The + no time warp mode is used. + + single_time_warp + The + single time warp mode is used. + + multi_time_warp + The + multi-time warp mode is used. + + + + + tolerant_timeofday + +

Returns whether a pre ERTS 7.0 backwards compatible + compensation for sudden changes of system time is enabled + or disabled. Such compensation is enabled when the + time offset + is final, and + + time correction is enabled.

+ + + + + + + + + + + + + + + + + + + + Information about system schedulers. + + +

Returns information about schedulers, scheduling and threads in the + current system as specified by Item:

+ + + dirty_cpu_schedulers + +

Returns the number of dirty CPU scheduler threads used by + the emulator. Dirty CPU schedulers execute CPU-bound + native functions, such as NIFs, linked-in driver code, + and BIFs that cannot be managed cleanly by the normal + emulator schedulers.

+

The number of dirty CPU scheduler threads is determined + at emulator boot time and cannot be changed after that. + However, the number of dirty CPU scheduler threads online + can be changed at any time. The number of dirty CPU + schedulers can be set at startup by passing + command-line flag + +SDcpu or +SDPcpu in erl(1).

See also @@ -7989,9 +8411,9 @@ ok erlang:system_flag(schedulers_online, SchedulersOnline).

 - dirty_cpu_schedulers_online + + dirty_cpu_schedulers_online -

Returns the number of dirty CPU schedulers online. The return value satisfies , @@ -8013,9 +8435,9 @@ ok erlang:system_flag(dirty_cpu_schedulers_online, DirtyCPUSchedulersOnline).

 - dirty_io_schedulers + + dirty_io_schedulers -

Returns the number of dirty I/O schedulers as an integer. Dirty I/O schedulers execute I/O-bound native functions, such as NIFs and linked-in driver code, which cannot be @@ -8032,685 +8454,540 @@ ok erlang:system_flag(dirty_cpu_schedulers_online, DirtyCPUSchedulersOnline).

 - dist + + multi_scheduling -

Returns a binary containing a string of distribution - information formatted as in Erlang crash dumps. For more - information, see section - How to interpret the Erlang crash dumps - in the User's Guide.

+

Returns one of the following:

+ + disabled + +

The emulator has been started with only one scheduler thread.

+ + blocked + +

The emulator has more than one scheduler thread, + but all scheduler threads except one are blocked. + That is, only one scheduler thread schedules + Erlang processes and executes Erlang code.

+ + blocked_normal + +

The emulator has more than one scheduler thread, + but all normal scheduler threads except one are + blocked. Notice that dirty schedulers are not + blocked, and can schedule Erlang processes and + execute native code.

+ + enabled + +

The emulator has more than one scheduler thread, + and no scheduler threads are blocked. That is, + all available scheduler threads schedule + Erlang processes and execute Erlang code.

+ + +

See also + + erlang:system_flag(multi_scheduling, BlockState), + + erlang:system_info(multi_scheduling_blockers), + + erlang:system_info(normal_multi_scheduling_blockers), + and + erlang:system_info(schedulers).

 - dist_buf_busy_limit + + multi_scheduling_blockers - -

Returns the value of the distribution buffer busy limit - in bytes. This limit can be set at startup by passing - command-line flag - +zdbbl - to erl(1).

+

Returns a list of Pids when + multi-scheduling is blocked, otherwise the empty list is + returned. The Pids in the list + represent all the processes currently + blocking multi-scheduling. A Pid occurs + only once in the list, even if the corresponding + process has blocked multiple times.

+

See also + + erlang:system_flag(multi_scheduling, BlockState), + + erlang:system_info(multi_scheduling), + + erlang:system_info(normal_multi_scheduling_blockers), + and + erlang:system_info(schedulers).

 - dist_ctrl + + normal_multi_scheduling_blockers -

Returns a list of tuples - {Node, ControllingEntity}, - one entry for each connected remote node. - Node is the node name - and ControllingEntity is the port or process - identifier responsible for the communication to that node. - More specifically, ControllingEntity for - nodes connected through TCP/IP (the normal case) is the socket - used in communication with the specific node.

+

Returns a list of Pids when + normal multi-scheduling is blocked (that is, all normal schedulers + but one is blocked), otherwise the empty list is returned. + The Pids in the list represent all the + processes currently blocking normal multi-scheduling. + A Pid occurs only once in the list, even if + the corresponding process has blocked multiple times.

+

See also + + erlang:system_flag(multi_scheduling, BlockState), + + erlang:system_info(multi_scheduling), + + erlang:system_info(multi_scheduling_blockers), + and + erlang:system_info(schedulers).

 - driver_version + + scheduler_bind_type -

Returns a string containing the Erlang driver version - used by the runtime system. It has the form - - "<major ver>.<minor ver>".

+

Returns information about how the user has requested + schedulers to be bound or not bound.

+

Notice that although a user has requested + schedulers to be bound, they can silently have failed + to bind. To inspect the scheduler bindings, call + + erlang:system_info(scheduler_bindings).

+

For more information, see command-line argument + +sbt + in erl(1) and + + erlang:system_info(scheduler_bindings).

 - dynamic_trace + + scheduler_bindings -

Returns an atom describing the dynamic trace framework - compiled into the virtual machine. It can be - dtrace, systemtap, or none. For a - commercial or standard build, it is always none. - The other return values indicate a custom configuration - (for example, ./configure --with-dynamic-trace=dtrace). - For more information about dynamic tracing, see - - dyntrace(3) manual page and the - README.dtrace/README.systemtap files in the - Erlang source code top directory.

+

Returns information about the currently used scheduler + bindings.

+

A tuple of a size equal to + + erlang:system_info(schedulers) + is returned. The tuple elements are integers + or the atom unbound. Logical processor identifiers + are represented as integers. The Nth + element of the tuple equals the current binding for + the scheduler with the scheduler identifier equal to + N. For example, if the schedulers are bound, + element(erlang:system_info(scheduler_id), + erlang:system_info(scheduler_bindings)) returns + the identifier of the logical processor that the calling + process is executing on.

+

Notice that only schedulers online can be bound to logical + processors.

+

For more information, see command-line argument + +sbt + in erl(1) and + + erlang:system_info(schedulers_online).

 - dynamic_trace_probes + + scheduler_id -

Returns a boolean() indicating if dynamic trace - probes (dtrace or systemtap) are built into - the emulator. This can only be true if the virtual - machine was built for dynamic tracing (that is, - system_info(dynamic_trace) returns - dtrace or systemtap).

+

Returns the scheduler ID (SchedulerId) of the + scheduler thread that the calling process is executing + on. SchedulerId is a positive integer, + where .

+

See also + + erlang:system_info(schedulers).

 - end_time + + schedulers -

The last Erlang monotonic - time in native - time unit that - can be represented internally in the current Erlang runtime system - instance. The time between the - start time and - the end time is at least a quarter of a millennium.

+

Returns the number of scheduler threads used by + the emulator. Scheduler threads online schedules Erlang + processes and Erlang ports, and execute Erlang code + and Erlang linked-in driver code.

+

The number of scheduler threads is determined at + emulator boot time and cannot be changed later. + However, the number of schedulers online can + be changed at any time.

+

See also + + erlang:system_flag(schedulers_online, + SchedulersOnline), + + erlang:system_info(schedulers_online), + + erlang:system_info(scheduler_id), + + erlang:system_flag(multi_scheduling, BlockState), + + erlang:system_info(multi_scheduling), + + erlang:system_info(normal_multi_scheduling_blockers) + and + erlang:system_info(multi_scheduling_blockers). +

- elib_malloc + + schedulers_online -

This option will be removed in a future release. - The return value will always be false, as the - elib_malloc allocator has been removed.

+

Returns the number of schedulers online. The scheduler + identifiers of schedulers online satisfy the relationship + .

+

For more information, see + + erlang:system_info(schedulers) and + + erlang:system_flag(schedulers_online, + SchedulersOnline).

 - ets_limit + + smp_support -

Returns the maximum number of ETS tables allowed. This - limit can be increased at startup by passing - command-line flag - +e to - erl(1) or by setting environment variable - ERL_MAX_ETS_TABLES before starting the Erlang - runtime system.

+

Returns true.

 - heap_sizes + + threads -

Returns a list of integers representing valid heap sizes - in words. All Erlang heaps are sized from sizes in this - list.

+

Returns true.

 - heap_type + + thread_pool_size -

Returns the heap type used by the current emulator. One - heap type exists:

- - private - - Each process has a heap reserved for its use and no - references between heaps of different processes are - allowed. Messages passed between processes are copied - between heaps. - - + +

Returns the number of async threads in the async thread + pool used for asynchronous driver calls + ( + erl_driver:driver_async()). + The value is given as an integer.

 - info + + + + + + + + + + + Information about erlang distribution. + + +

Returns information about Erlang Distribution in the + current system as specified by Item:

+ + + creation -

Returns a binary containing a string of miscellaneous - system information formatted as in Erlang crash dumps. - For more information, see section - - How to interpret the Erlang crash dumps - in the User's Guide.

+

Returns the creation of the local node as an integer. + The creation is changed when a node is restarted. The + creation of a node is stored in process identifiers, port + identifiers, and references. This makes it (to some + extent) possible to distinguish between identifiers from + different incarnations of a node. The valid + creations are integers in the range 1..3, but this will + probably change in a future release. If the node is not + alive, 0 is returned.

 - kernel_poll + + delayed_node_table_gc -

Returns true if the emulator uses some kind of - kernel-poll implementation, otherwise false.

+

Returns the amount of time in seconds garbage collection + of an entry in a node table is delayed. This limit can be set + on startup by passing command-line flag + +zdntgc + to erl(1). For more information, see the documentation of + the command-line flag.

 - loaded + + dist -

Returns a binary containing a string of loaded module +

Returns a binary containing a string of distribution information formatted as in Erlang crash dumps. For more - information, see section - How to interpret the Erlang - crash dumps in the User's Guide.

- - logical_processors - - -

Returns the detected number of logical processors configured - in the system. The return value is either an integer, or - the atom unknown if the emulator cannot - detect the configured logical processors.

- - logical_processors_available - - -

Returns the detected number of logical processors available - to the Erlang runtime system. The return value is either an - integer, or the atom unknown if the emulator - cannot detect the available logical processors. The number - of available logical processors is less than or equal to - the number of - logical processors online.

- - logical_processors_online - - -

Returns the detected number of logical processors online on - the system. The return value is either an integer, - or the atom unknown if the emulator cannot - detect logical processors online. The number of logical - processors online is less than or equal to the number of - logical processors - configured.

- - machine - -

Returns a string containing the Erlang machine name.

+ information, see section + How to interpret the Erlang crash dumps + in the User's Guide.

 - modified_timing_level + + dist_buf_busy_limit -

Returns the modified timing-level (an integer) if - modified timing is enabled, otherwise undefined. - For more information about modified timing, see +

Returns the value of the distribution buffer busy limit + in bytes. This limit can be set at startup by passing command-line flag - +T - in erl(1)

- - multi_scheduling - - -

Returns one of the following:

- - disabled - -

The emulator has been started with only one scheduler thread.

- - blocked - -

The emulator has more than one scheduler thread, - but all scheduler threads except one are blocked. - That is, only one scheduler thread schedules - Erlang processes and executes Erlang code.

- - blocked_normal - -

The emulator has more than one scheduler thread, - but all normal scheduler threads except one are - blocked. Notice that dirty schedulers are not - blocked, and can schedule Erlang processes and - execute native code.

- - enabled - -

The emulator has more than one scheduler thread, - and no scheduler threads are blocked. That is, - all available scheduler threads schedule - Erlang processes and execute Erlang code.

- - -

See also - - erlang:system_flag(multi_scheduling, BlockState), - - erlang:system_info(multi_scheduling_blockers), - - erlang:system_info(normal_multi_scheduling_blockers), - and - erlang:system_info(schedulers).

- - multi_scheduling_blockers - - -

Returns a list of Pids when - multi-scheduling is blocked, otherwise the empty list is - returned. The Pids in the list - represent all the processes currently - blocking multi-scheduling. A Pid occurs - only once in the list, even if the corresponding - process has blocked multiple times.

-

See also - - erlang:system_flag(multi_scheduling, BlockState), - - erlang:system_info(multi_scheduling), - - erlang:system_info(normal_multi_scheduling_blockers), - and - erlang:system_info(schedulers).

- - nif_version - -

Returns a string containing the version of the Erlang NIF - interface used by the runtime system. It is on the form - "<major ver>.<minor ver>".

+ +zdbbl + to erl(1).

 - normal_multi_scheduling_blockers + + dist_ctrl - -

Returns a list of Pids when - normal multi-scheduling is blocked (that is, all normal schedulers - but one is blocked), otherwise the empty list is returned. - The Pids in the list represent all the - processes currently blocking normal multi-scheduling. - A Pid occurs only once in the list, even if - the corresponding process has blocked multiple times.

-

See also - - erlang:system_flag(multi_scheduling, BlockState), - - erlang:system_info(multi_scheduling), - - erlang:system_info(multi_scheduling_blockers), - and - erlang:system_info(schedulers).

+

Returns a list of tuples + {Node, ControllingEntity}, + one entry for each connected remote node. + Node is the node name + and ControllingEntity is the port or process + identifier responsible for the communication to that node. + More specifically, ControllingEntity for + nodes connected through TCP/IP (the normal case) is the socket + used in communication with the specific node.

 - - otp_release + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Information about the system. + + +

Returns various information about the current system + (emulator) as specified by Item:

+ + + build_type - -

Returns a string containing the OTP release number of the - OTP release that the currently executing ERTS application - is part of.

-

As from Erlang/OTP 17, the OTP release number corresponds to - the major OTP version number. No - erlang:system_info() argument gives the exact OTP - version. This is because the exact OTP version in the general case - is difficult to determine. For more information, see the - description of versions in - - System principles in System Documentation.

+

Returns an atom describing the build type of the runtime + system. This is normally the atom opt for optimized. + Other possible return values are debug, purify, + quantify, purecov, gcov, valgrind, + gprof, and lcnt. Possible return values + can be added or removed at any time without prior notice.

 - - os_monotonic_time_source + + c_compiler_used -

Returns a list containing information about the source of - OS - monotonic time that is used by the runtime system.

-

If [] is returned, no OS monotonic time is - available. The list contains two-tuples with Keys - as first element, and Values as second element. The - order of these tuples is undefined. The following - tuples can be part of the list, but more tuples can be - introduced in the future:

- - {function, Function} -

Function is the name of the function - used. This tuple always exists if OS monotonic time is - available to the runtime system.

- - {clock_id, ClockId} -

This tuple only exists if Function - can be used with different clocks. ClockId - corresponds to the clock identifier used when calling - Function.

- - {resolution, OsMonotonicTimeResolution} -

Highest possible - - resolution - of current OS monotonic time source as parts per - second. If no resolution information can be retrieved - from the OS, OsMonotonicTimeResolution is - set to the resolution of the time unit of - Functions return value. That is, the actual - resolution can be lower than - OsMonotonicTimeResolution. Notice that - the resolution does not say anything about the - - accuracy or whether the - - precision aligns with the resolution. You do, - however, know that the precision is not better than - OsMonotonicTimeResolution.

- - {extended, Extended} -

Extended equals yes if - the range of time values has been extended; - otherwise Extended equals no. The - range must be extended if Function - returns values that wrap fast. This typically - is the case when the return value is a 32-bit value.

- - {parallel, Parallel} -

Parallel equals yes if - Function is called in parallel from multiple - threads. If it is not called in parallel, because - calls must be serialized, Parallel equals - no.

- - {time, OsMonotonicTime} -

OsMonotonicTime equals current OS - monotonic time in native - time unit.

- - +

Returns a two-tuple describing the C compiler used when + compiling the runtime system. The first element is an + atom describing the name of the compiler, or undefined + if unknown. The second element is a term describing the + version of the compiler, or undefined if unknown.

 - - os_system_time_source + + check_io -

Returns a list containing information about the source of - OS - system time that is used by the runtime system.

-

The list contains two-tuples with Keys - as first element, and Values as second element. The - order if these tuples is undefined. The following - tuples can be part of the list, but more tuples can be - introduced in the future:

- - {function, Function} -

Function is the name of the funcion used.

- - {clock_id, ClockId} -

Exists only if Function - can be used with different clocks. ClockId - corresponds to the clock identifier used when calling - Function.

- - {resolution, OsSystemTimeResolution} -

Highest possible - - resolution - of current OS system time source as parts per - second. If no resolution information can be retrieved - from the OS, OsSystemTimeResolution is - set to the resolution of the time unit of - Functions return value. That is, the actual - resolution can be lower than - OsSystemTimeResolution. Notice that - the resolution does not say anything about the - - accuracy or whether the - - precision do align with the resolution. You do, - however, know that the precision is not better than - OsSystemTimeResolution.

- - {parallel, Parallel} -

Parallel equals yes if - Function is called in parallel from multiple - threads. If it is not called in parallel, because - calls needs to be serialized, Parallel equals - no.

- - {time, OsSystemTime} -

OsSystemTime equals current OS - system time in native - time unit.

- - +

Returns a list containing miscellaneous information + about the emulators internal I/O checking. Notice that + the content of the returned list can vary between + platforms and over time. It is only guaranteed + that a list is returned.

 - port_parallelism + + compat_rel - -

Returns the default port parallelism scheduling hint used. - For more information, see command-line argument - +spp - in erl(1).

+

Returns the compatibility mode of the local node as + an integer. The integer returned represents the + Erlang/OTP release that the current emulator has been + set to be backward compatible with. The compatibility + mode can be configured at startup by using command-line flag + +R in + erl(1).

 - port_count + + debug_compiled -

Returns the number of ports currently existing at the - local node. The value is given as an integer. This is - the same value as returned by - length(erlang:ports()), but more efficient.

+

Returns true if the emulator has been + debug-compiled, otherwise false.

 - port_limit + + driver_version - -

Returns the maximum number of simultaneously existing - ports at the local node as an integer. This limit can be - configured at startup by using command-line flag - +Q in erl(1).

+

Returns a string containing the Erlang driver version + used by the runtime system. It has the form + + "<major ver>.<minor ver>".

 - - process_count + + dynamic_trace -

Returns the number of processes currently existing at the - local node. The value is given as an integer. This is - the same value as returned by - length(processes()), but more efficient.

+

Returns an atom describing the dynamic trace framework + compiled into the virtual machine. It can be + dtrace, systemtap, or none. For a + commercial or standard build, it is always none. + The other return values indicate a custom configuration + (for example, ./configure --with-dynamic-trace=dtrace). + For more information about dynamic tracing, see + + dyntrace(3) manual page and the + README.dtrace/README.systemtap files in the + Erlang source code top directory.

 - process_limit + + dynamic_trace_probes - -

Returns the maximum number of simultaneously existing - processes at the local node. The value is given as an - integer. This limit can be configured at startup by using - command-line flag +P - in erl(1).

+

Returns a boolean() indicating if dynamic trace + probes (dtrace or systemtap) are built into + the emulator. This can only be true if the virtual + machine was built for dynamic tracing (that is, + system_info(dynamic_trace) returns + dtrace or systemtap).

 - procs + + info -

Returns a binary containing a string of process and port - information formatted as in Erlang crash dumps. For more - information, see section +

Returns a binary containing a string of miscellaneous + system information formatted as in Erlang crash dumps. + For more information, see section + How to interpret the Erlang crash dumps in the User's Guide.

 - scheduler_bind_type + + kernel_poll - -

Returns information about how the user has requested - schedulers to be bound or not bound.

-

Notice that although a user has requested - schedulers to be bound, they can silently have failed - to bind. To inspect the scheduler bindings, call - - erlang:system_info(scheduler_bindings).

-

For more information, see command-line argument - +sbt - in erl(1) and - - erlang:system_info(scheduler_bindings).

+

Returns true if the emulator uses some kind of + kernel-poll implementation, otherwise false.

 - scheduler_bindings + + loaded - -

Returns information about the currently used scheduler - bindings.

-

A tuple of a size equal to - - erlang:system_info(schedulers) - is returned. The tuple elements are integers - or the atom unbound. Logical processor identifiers - are represented as integers. The Nth - element of the tuple equals the current binding for - the scheduler with the scheduler identifier equal to - N. For example, if the schedulers are bound, - element(erlang:system_info(scheduler_id), - erlang:system_info(scheduler_bindings)) returns - the identifier of the logical processor that the calling - process is executing on.

-

Notice that only schedulers online can be bound to logical - processors.

-

For more information, see command-line argument - +sbt - in erl(1) and - - erlang:system_info(schedulers_online).

+

Returns a binary containing a string of loaded module + information formatted as in Erlang crash dumps. For more + information, see section + How to interpret the Erlang + crash dumps in the User's Guide.

 - scheduler_id + + machine - -

Returns the scheduler ID (SchedulerId) of the - scheduler thread that the calling process is executing - on. SchedulerId is a positive integer, - where .

-

See also - - erlang:system_info(schedulers).

+

Returns a string containing the Erlang machine name.

 - schedulers + + modified_timing_level - -

Returns the number of scheduler threads used by - the emulator. Scheduler threads online schedules Erlang - processes and Erlang ports, and execute Erlang code - and Erlang linked-in driver code.

-

The number of scheduler threads is determined at - emulator boot time and cannot be changed later. - However, the number of schedulers online can - be changed at any time.

-

See also - - erlang:system_flag(schedulers_online, - SchedulersOnline), - - erlang:system_info(schedulers_online), - - erlang:system_info(scheduler_id), - - erlang:system_flag(multi_scheduling, BlockState), - - erlang:system_info(multi_scheduling), - - erlang:system_info(normal_multi_scheduling_blockers) - and - erlang:system_info(multi_scheduling_blockers). -

+

Returns the modified timing-level (an integer) if + modified timing is enabled, otherwise undefined. + For more information about modified timing, see + command-line flag + +T + in erl(1)

 - schedulers_online + + nif_version - -

Returns the number of schedulers online. The scheduler - identifiers of schedulers online satisfy the relationship - .

-

For more information, see - - erlang:system_info(schedulers) and - - erlang:system_flag(schedulers_online, - SchedulersOnline).

+

Returns a string containing the version of the Erlang NIF + interface used by the runtime system. It is on the form + "<major ver>.<minor ver>".

 - smp_support + + otp_release -

Returns true.

+ +

Returns a string containing the OTP release number of the + OTP release that the currently executing ERTS application + is part of.

+

As from Erlang/OTP 17, the OTP release number corresponds to + the major OTP version number. No + erlang:system_info() argument gives the exact OTP + version. This is because the exact OTP version in the general case + is difficult to determine. For more information, see the + description of versions in + + System principles in System Documentation.

 - start_time + + port_parallelism -

The Erlang monotonic - time in native - time unit at the - time when current Erlang runtime system instance started.

-

See also - erlang:system_info(end_time).

+

Returns the default port parallelism scheduling hint used. + For more information, see command-line argument + +spp + in erl(1).

 - system_version + + system_version

Returns a string containing version number and some important properties, such as the number of schedulers.

 - system_architecture + + system_architecture

Returns a string containing the processor and OS architecture the emulator is built for.

 - threads - -

Returns true.

- - thread_pool_size - - -

Returns the number of async threads in the async thread - pool used for asynchronous driver calls - ( - erl_driver:driver_async()). - The value is given as an integer.

- - time_correction - - -

Returns a boolean value indicating whether - - time correction is enabled or not.

- - time_offset - - -

Returns the state of the time offset:

- - preliminary - -

The time offset is preliminary, and will be changed - and finalized later. The preliminary time offset - is used during the preliminary phase of the - - single time warp mode.

- - final - -

The time offset is final. This either because - - no time warp mode is used, or because the time - offset have been finalized when - - single time warp mode is used.

- - volatile - -

The time offset is volatile. That is, it can - change at any time. This is because - - multi-time warp mode is used.

- - - - - time_warp_mode - -

Returns a value identifying the - - time warp mode that is used:

- - no_time_warp - The - no time warp mode is used. - - single_time_warp - The - single time warp mode is used. - - multi_time_warp - The - multi-time warp mode is used. - - - - tolerant_timeofday - - -

Returns whether a pre ERTS 7.0 backwards compatible - compensation for sudden changes of system time is enabled - or disabled. Such compensation is enabled when the - time offset - is final, and - - time correction is enabled.

- - trace_control_word + + trace_control_word

Returns the value of the node trace control word. For more information, see function get_tcw in section Match Specifications in Erlang in the User's Guide.

 - update_cpu_info - - -

The runtime system rereads the CPU information available - and updates its internally stored information about the - detected - CPU topology and the number of logical processors - configured, - online, - and - available.

-

If the CPU information has changed since the last time - it was read, the atom changed is returned, otherwise - the atom unchanged. If the CPU information has changed, - you probably want to - adjust the - number of schedulers online. You typically want - to have as many schedulers online as - logical - processors available.

- - version + + version -

Returns a string containing the version number of the emulator.

 - wordsize + + wordsize

Same as {wordsize, internal}.

 @@ -8732,13 +9009,6 @@ ok 64-bit architecture, 8 is returned.

 - -

Argument scheduler has changed name to - scheduler_id to avoid mix up with argument - schedulers. Argument scheduler was - introduced in ERTS 5.5 and renamed in - ERTS 5.5.1.

- diff --git a/erts/doc/src/notes.xml b/erts/doc/src/notes.xml index 3109da6738..7ef42c2318 100644 --- a/erts/doc/src/notes.xml +++ b/erts/doc/src/notes.xml @@ -10964,7 +10964,7 @@ update_cpu_info will make the runtime system reread and update the internally stored CPU information. For more information see the documentation of erlang:system_info(update_cpu_info).

+ marker="erlang#system_info_update_cpu_info">erlang:system_info(update_cpu_info).

The CPU topology is now automatically detected on Windows systems with less than 33 logical processors. The runtime diff --git a/erts/preloaded/src/erlang.erl b/erts/preloaded/src/erlang.erl index d352e11751..370ecdc3f6 100644 --- a/erts/preloaded/src/erlang.erl +++ b/erts/preloaded/src/erlang.erl @@ -2563,9 +2563,9 @@ tuple_to_list(_Tuple) -> Settings :: [{Subsystem :: atom(), [{Parameter :: atom(), Value :: term()}]}]; - (alloc_util_allocators) -> [Alloc] when - Alloc :: atom(); ({allocator, Alloc}) -> [_] when %% More or less anything + Alloc :: atom(); + (alloc_util_allocators) -> [Alloc] when Alloc :: atom(); ({allocator_sizes, Alloc}) -> [_] when %% More or less anything Alloc :: atom(); @@ -2593,6 +2593,7 @@ tuple_to_list(_Tuple) -> (driver_version) -> string(); (dynamic_trace) -> none | dtrace | systemtap; (dynamic_trace_probes) -> boolean(); + (end_time) -> non_neg_integer(); (elib_malloc) -> false; (eager_check_io) -> boolean(); (ets_limit) -> pos_integer(); @@ -2620,6 +2621,7 @@ tuple_to_list(_Tuple) -> (otp_release) -> string(); (os_monotonic_time_source) -> [{atom(),term()}]; (os_system_time_source) -> [{atom(),term()}]; + (port_parallelism) -> boolean(); (port_count) -> non_neg_integer(); (port_limit) -> pos_integer(); (process_count) -> pos_integer(); @@ -2649,7 +2651,8 @@ tuple_to_list(_Tuple) -> (trace_control_word) -> non_neg_integer(); (update_cpu_info) -> changed | unchanged; (version) -> string(); - (wordsize | {wordsize, internal} | {wordsize, external}) -> 4 | 8. + (wordsize | {wordsize, internal} | {wordsize, external}) -> 4 | 8; + (overview) -> boolean(). system_info(_Item) -> erlang:nif_error(undefined). -- cgit v1.2.3