From db5f5eeaa8ffab49758beb95552c1cf14b49a55d Mon Sep 17 00:00:00 2001 From: Sverker Eriksson Date: Thu, 1 Oct 2015 18:57:21 +0200 Subject: erts: Review newer additions to erlang.xml Trying to adopt same style as done by xsipewe in e17e236cd1661bc for later additions. --- erts/doc/src/erlang.xml | 274 ++++++++++++++++++++++++------------------------ 1 file changed, 136 insertions(+), 138 deletions(-) (limited to 'erts') diff --git a/erts/doc/src/erlang.xml b/erts/doc/src/erlang.xml index a51774b9f0..221869799d 100644 --- a/erts/doc/src/erlang.xml +++ b/erts/doc/src/erlang.xml @@ -66,7 +66,7 @@ -

Currently supported time unit representations:

+

Supported time unit representations:

PartsPerSecond :: integer() >= 1

Time unit expressed in parts per second. That is, @@ -93,11 +93,11 @@ used by the Erlang runtime system.

The native time unit is determined at - runtime system start, and will remain the same until + runtime system start, and remains the same until the runtime system terminates. If a runtime system is stopped and then started again (even on the same machine), the native time unit of the new - runtime system instance may differ from the + runtime system instance can differ from the native time unit of the old runtime system instance.

@@ -106,8 +106,7 @@ seconds, native). The result equals the number of whole native time units per second. In case the number of native time units per second does - not add up to a whole number, the result will be - rounded downwards.

+ not add up to a whole number, the result is rounded downwards.

The value of the native time unit gives @@ -121,7 +120,7 @@ but it gives absolutely no information at all about the accuracy of time values. The resolution of the native time - unit and the resolution of time values may differ + unit and the resolution of time values can differ significantly.

 @@ -578,7 +577,7 @@ TimerRef identifies the timer, and was returned by the BIF that created the timer.

-

Currently available Options:

+

Available Options:

{async, Async} @@ -587,7 +586,7 @@ defaults to false which will cause the cancellation to be performed synchronously. When Async is set to true, the cancel - operation will be performed asynchronously. That is, + operation is performed asynchronously. That is, erlang:cancel_timer() will send an asynchronous request for cancellation to the timer service that manages the timer, and then return ok. @@ -598,17 +597,17 @@

Request information about the Result of the cancellation. Info defaults to true - which means that the Result will - be given. When Info is set to false, no + which means the Result is + given. When Info is set to false, no information about the result of the cancellation - will be given. When the operation is performed

+ is given. When the operation is performed

synchronously

- If Info is true, the Result will + If Info is true, the Result is returned by erlang:cancel_timer(); otherwise, - ok will be returned. + ok is returned.

asynchronously @@ -616,10 +615,10 @@

If Info is true, a message on the form {cancel_timer, TimerRef, - Result} will be sent to the + Result} is sent to the caller of erlang:cancel_timer() when the cancellation operation has been performed; otherwise, - no message will be sent. + no message is sent.

@@ -628,30 +627,30 @@

More Options may be added in the future.

+

If Result is an integer, it represents + the time in milli-seconds left until the canceled timer would + have expired.

- When the Result equals false, a + If Result is false, a timer corresponding to TimerRef could not be found. This can be either because the timer had expired, already had been canceled, or because TimerRef - never has corresponded to a timer. If the timer has expired, - the timeout message has been sent, but it does not tell you - whether or not it has arrived at its destination yet. When the - Result is an integer, it represents the - time in milli-seconds left until the timer would have expired. + never corresponded to a timer. Even if the timer had expired, + it does not tell you whether or not the timeout message has + arrived at its destination yet.

The timer service that manages the timer may be co-located with another scheduler than the scheduler that the calling process is executing on. If this is the case, communication - with the timer service will take much longer time than if it + with the timer service takes much longer time than if it is located locally. If the calling process is in critical path, and can do other things while waiting for the result of this operation, or is not interested in the result of - the operation, you want to use the {async, true} - option. If using the {async, false} option, the calling - process will be blocked until the operation has been - performed. + the operation, you want to use option {async, true}. + If using option {async, false}, the calling + process blocks until the operation has been performed.

See also @@ -2537,7 +2536,7 @@ os_prompt% Returns a unique reference. -

Return a unique +

Returns a unique reference. The reference is unique among connected nodes.

Known issue: When a node is restarted multiple @@ -2863,7 +2862,7 @@ os_prompt% following format if the monitored state is changed:

{Tag, MonitorRef, Type, Object, Info}

The monitor request is an asynchronous signal. That is, it - takes time before the signal reach its destination.

 + takes time before the signal reaches its destination.

Valid Types:

process @@ -2976,8 +2975,8 @@ os_prompt% single time warp mode is used. When a change from preliminary to final time offset is made, the monitor will be triggered once - regardless of whether the time offset value was changed due to - the finalization or not.

+ regardless of whether the time offset value was actually changed + or not.

If the runtime system is in multi @@ -3077,7 +3076,7 @@ os_prompt% - Current Erlang monotonic time + Current Erlang monotonic time.

Returns the current Erlang @@ -3090,7 +3089,7 @@ os_prompt% monotonically increasing time, but not a strictly monotonically increasing time. That is, consecutive calls to - erlang:monotonic_time/0 may produce the same result.

+ erlang:monotonic_time/0 can produce the same result.

Different runtime system instances will use different unspecified points in time as base for their Erlang monotonic clocks. @@ -3098,9 +3097,9 @@ os_prompt% different runtime system instances. Different runtime system instances may also place this unspecified point in time different relative runtime system start. It may be placed in the future (time at start - will be a negative value), the past (time at start will be a - positive value), or the runtime system start (time at start will - be zero). The monotonic time as of runtime system start can be + is a negative value), the past (time at start is a + positive value), or the runtime system start (time at start is + zero). The monotonic time at runtime system start can be retrieved by calling erlang:system_info(start_time).

 @@ -4881,7 +4880,7 @@ os_prompt% TimerRef identifies the timer, and was returned by the BIF that created the timer.

-

Currently available Options:

+

Available Options:

{async, Async} @@ -4889,12 +4888,12 @@ os_prompt% Asynchronous request for state information. Async defaults to false which will cause the operation to be performed synchronously. In this case, the Result - will be returned by erlang:read_timer(). When - Async is set to true, erlang:read_timer() - will send an asynchronous request for the state information - to the timer service that manages the timer, and then return + is returned by erlang:read_timer(). When + Async is true, erlang:read_timer() + sends an asynchronous request for the state information + to the timer service that manages the timer, and then returns ok. A message on the format {read_timer, - TimerRef, Result} will be + TimerRef, Result} is sent to the caller of erlang:read_timer() when the operation has been processed.

@@ -4904,26 +4903,27 @@ os_prompt% More Options may be added in the future.

- When the Result equals false, a + If Result is an integer, it represents the + time in milli-seconds left until the timer expires.

+

+ If Result is false, a timer corresponding to TimerRef could not - be found. This can be either because the timer had expired, - had been canceled, or because TimerRef - never has corresponded to a timer. If the timer has expired, - the timeout message has been sent, but it does not tell you - whether or not it has arrived at its destination yet. When the - Result is an integer, it represents the - time in milli-seconds left until the timer expires. + be found. This can be because the timer had expired, + it had been canceled, or because TimerRef + never has corresponded to a timer. Even if the timer has expired, + it does not tell you whether or not the timeout message has + arrived at its destination yet.

The timer service that manages the timer may be co-located with another scheduler than the scheduler that the calling process is executing on. If this is the case, communication - with the timer service will take much longer time than if it + with the timer service takes much longer time than if it is located locally. If the calling process is in critical path, and can do other things while waiting for the result - of this operation you want to use the {async, true} - option. If using the {async, false} option, the calling + of this operation, you want to use option {async, true}. + If using option {async, false}, the calling process will be blocked until the operation has been performed.

@@ -5119,10 +5119,9 @@ true

Starts a timer. When the timer expires, the message - Msg will be sent to the process + Msg is sent to the process identified by Dest. Appart from - the format of the message sent to - Dest when the timer expires + the format of the timeout message, erlang:send_after/4 works exactly as erlang:start_timer/4.

 @@ -5609,24 +5608,27 @@ true

Starts a timer. When the timer expires, the message {timeout, TimerRef, Msg} - will be sent to the process identified by + is sent to the process identified by Dest.

-

Currently available Options:

+

Available Options:

- {abs, Abs} + {abs, false}

- Absolute Time value. Abs - defaults to false which means that the - Time value will be interpreted - as a time in milli-seconds relative current + This is the default. It means the + Time value is interpreted + as a time in milli-seconds relative current Erlang - monotonic time. When Abs is set to - true, the Time value will - be interpreted as an absolute Erlang monotonic time of - milli-seconds - time unit. + monotonic time. +

+ + {abs, true} + +

+ Absolute Time value. The + Time value is interpreted as an + absolute Erlang monotonic time in milli-seconds.

@@ -5634,7 +5636,7 @@ true More Options may be added in the future.

- The absolute point in time that the timer is set to expire on + The absolute point in time, the timer is set to expire on, has to be in the interval [erlang:system_info(start_time), erlang:system_info(end_time)]. @@ -5646,7 +5648,7 @@ true be a pid() of a process created on the current runtime system instance. This process may or may not have terminated. If Dest is an - atom(), it will be interpreted as the name of a + atom(), it is interpreted as the name of a locally registered process. The process referred to by the name is looked up at the time of timer expiration. No error is given if the name does not refer to a process. @@ -5654,7 +5656,7 @@ true

If Dest is a pid(), the timer is automatically canceled if the process referred to by the - pid() is not alive, or when the process exits. This + pid() is not alive, or if the process exits. This feature was introduced in ERTS version 5.4.11. Notice that timers are not automatically canceled when Dest is an atom(). @@ -5990,7 +5992,7 @@ ok +sct in erl(1).

When this argument is removed, a final CPU topology - to use will be determined at emulator boot time.

+ to use is determined at emulator boot time.

Sets the user-defined CpuTopology. The user-defined @@ -6152,7 +6154,7 @@ ok argument, use command-line argument +sbt in erl(1). When this argument is removed, a final scheduler bind - type to use will be determined at emulator boot time.

+ type to use is determined at emulator boot time.

Controls if and how schedulers are bound to logical processors.

@@ -6313,26 +6315,24 @@ ok

Finalizes the time offset - when the single - time warp mode is being used. If another time warp mode than - the "single time warp mode" is used, the time offset state will be left - unchanged.

-

Returns the old state identifier. That is, if:

+ when single + time warp mode is used. If another time warp mode + is used, the time offset state is left unchanged.

+

Returns the old state identifier. That is:

-

preliminary is returned, finalization was +

If preliminary is returned, finalization was performed and the time offset is now final.

 -

final is returned, the time offset was - already in the final state. This either due to another +

If final is returned, the time offset was + already in the final state. This either because another erlang:system_flag(time_offset, finalize) call, or - due to the - no - time warp mode being used.

 + because no + time warp mode is used.

 -

volatile is returned, the time offset - cannot be finalized due to the +

If volatile is returned, the time offset + cannot be finalized because multi - time warp mode being used.

 + time warp mode is used.

 @@ -6704,11 +6704,11 @@ ok delayed_node_table_gc -

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

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 the command line flag + +zdntgc + to erl. For more information see the documentation of the command line flag.

 dirty_cpu_schedulers @@ -6854,9 +6854,9 @@ ok eager_check_io

- Returns the value of the erl - +secio command line - flag which is either true or false. See the + Returns the value of the erl command line flag + +secio + which is either true or false. See the documentation of the command line flag for information about the different values.

@@ -7036,8 +7036,9 @@ ok nif_version -

Returns a string containing the erlang NIF version - used by the runtime system. It will be on the form "<major ver>.<minor ver>".

+

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>".

 otp_release @@ -7058,11 +7059,11 @@ ok

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

-

In case [] is returned, no OS monotonic time is +

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 if these tuples is undefined. Currently the following - tuples may be part of the list, but more tuples may be + 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} @@ -7081,18 +7082,17 @@ ok resolution of current OS monotonic time source as parts per second. If no resolution information can be retreived - from the OS, OsMonotonicTimeResolution will be + from the OS, OsMonotonicTimeResolution is set to the resolution of the time unit of Functions return value. That is, the actual - resolution may be lower than + resolution can be lower than OsMonotonicTimeResolution. Also note that the resolution does not say anything about the accuracy, - and that the + and whether the precision - might not align with the resolution. You do, - however, know that the precision won't be - better than + do align with the resolution. You do, + however, know that the precision is not better than OsMonotonicTimeResolution.

 {extended, Extended} @@ -7124,8 +7124,8 @@ ok 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. Currently the following - tuples may be part of the list, but more tuples may be + 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} @@ -7143,18 +7143,17 @@ ok resolution of current OS system time source as parts per second. If no resolution information can be retreived - from the OS, OsSystemTimeResolution will be + from the OS, OsSystemTimeResolution is set to the resolution of the time unit of Functions return value. That is, the actual resolution may be lower than OsSystemTimeResolution. Also note that the resolution does not say anything about the accuracy, - and that the + and whether the precision - might not align with the resolution. You do, - however, know that the precision won't be - better than + do align with the resolution. You do, + however, know that the precision is not better than OsSystemTimeResolution.

{parallel, Parallel} @@ -7353,19 +7352,18 @@ ok time warp mode.

final -

The time offset is final. This - either due to the use of the +

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

 + time warp mode is used.

volatile -

The time offset is volatile. That is, it may - change at any time. This due to the +

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

 + time warp mode is used.

 time_warp_mode @@ -7375,15 +7373,15 @@ ok no_time_warp

The no - time warp mode is being used.

 + time warp mode is used.

single_time_warp

The single - time warp mode is being used.

 + time warp mode is used.

multi_time_warp

The multi - time warp mode is being used.

 + time warp mode is used.

 tolerant_timeofday @@ -7862,8 +7860,8 @@ ok

Returns current Erlang system time on the format {MegaSecs, Secs, MicroSecs}. This format is - the same that os:timestamp/0 - and the now deprecated erlang:now/0 + the same as os:timestamp/0 + and the deprecated erlang:now/0 uses. The reason for the existence of erlang:timestamp() is purely to simplify usage for existing code that assumes this timestamp format. Current Erlang system time can more efficiently be retrieved in @@ -7877,7 +7875,7 @@ timestamp() -> Secs = ErlangSystemTime div 1000000 - MegaSecs*1000000, MicroSecs = ErlangSystemTime rem 1000000, {MegaSecs, Secs, MicroSecs}. -

It however use a native implementation which does +

The BIF uses a native implementation which does not build garbage on the heap and with slightly better performance.

@@ -8035,7 +8033,7 @@ timestamp() -> Only allowed with PidSpec==all. If the host machine OS does not support high-resolution CPU time measurements, trace/3 exits with - badarg. Note that most operating systems do + badarg. Notice that most OS do not synchronize this value across cores, so be prepared that time might seem to go backwards when using this option.

@@ -8708,17 +8706,17 @@ timestamp() -> Each integer value can of course be constructed by other means.

-

By default, i.e. when [] is passed as +

By default, when [] is passed as ModifierList, both negative and - positive integers will be returned. This is order - to be able to utilize the range of integers that do - not need to be heap allocated as much as possible. + positive integers can be returned. This in order + to utilize the range of integers that do + not need heap memory allocation as much as possible. By default the returned integers are also only - guaranteed to be unique, i.e., any integer returned - may be either smaller, or larger than previously + guaranteed to be unique, that is, any returned integer + can be smaller or larger than previously returned integers.

-

Currently valid Modifiers:

+

Valid Modifiers:

positive @@ -8736,7 +8734,7 @@ timestamp() -> returned will always be larger than previously returned integers on the current runtime system instance.

-

These values can be used when ordering events +

These values can be used to determine order between events on the runtime system instance. That is, if both X = erlang:unique_integer([monotonic]) and Y = erlang:unique_integer([monotonic]) are @@ -8746,15 +8744,15 @@ timestamp() -> before Y.

Strictly monotonically increasing values are inherently quite expensive to generate and scales - poorly. This since the values needs to be - synchronized. That is, do not pass the monotonic + poorly. This is because the values need to be + synchronized between cpu cores. That is, do not pass the monotonic modifier unless you really need strictly monotonically increasing values.

 -

All currently valid Modifiers +

All valid Modifiers can be combined. Repeated (valid) Modifiers in the ModifierList are ignored.

-- cgit v1.2.3