From 6487aac5977cf470bc6a2cd0964da2850ee38717 Mon Sep 17 00:00:00 2001 From: Rickard Green Date: Thu, 30 Oct 2014 23:57:01 +0100 Subject: Introduce a new time API The old time API is based on erlang:now/0. The major issue with erlang:now/0 is that it was intended to be used for so many unrelated things. This tied these unrelated operations together and unnecessarily caused performance, scalability as well as accuracy, and precision issues for operations that do not need to have such issues. The new API spreads different functionality over multiple functions in order to improve on this. The new API consists of a number of new BIFs: - erlang:convert_time_unit/3 - erlang:monotonic_time/0 - erlang:monotonic_time/1 - erlang:system_time/0 - erlang:system_time/1 - erlang:time_offset/0 - erlang:time_offset/1 - erlang:timestamp/0 - erlang:unique_integer/0 - erlang:unique_integer/1 - os:system_time/0 - os:system_time/1 and a number of extensions of existing BIFs: - erlang:monitor(time_offset, clock_service) - erlang:system_flag(time_offset, finalize) - erlang:system_info(os_monotonic_time_source) - erlang:system_info(time_offset) - erlang:system_info(time_warp_mode) - erlang:system_info(time_correction) - erlang:system_info(start_time) See the "Time and Time Correction in Erlang" chapter of the ERTS User's Guide for more information. --- erts/doc/src/erlang.xml | 775 +++++++++++++++++++++++++++++++++++++++++------- 1 file changed, 672 insertions(+), 103 deletions(-) (limited to 'erts/doc/src/erlang.xml') diff --git a/erts/doc/src/erlang.xml b/erts/doc/src/erlang.xml index 483d81cfb6..3cbfd372ce 100644 --- a/erts/doc/src/erlang.xml +++ b/erts/doc/src/erlang.xml @@ -58,7 +58,71 @@ -

See now/0.

+

See erlang:timestamp/0.

+ + + + + +

Currently supported time unit representations:

+ + PartsPerSecond :: integer() >= 1 +

Time unit expressed in parts per second. That is, + the time unit equals 1/PartsPerSecond second.

 + + seconds +

Symbolic representation of the time unit + represented by the integer 1.

 + + milli_seconds +

Symbolic representation of the time unit + represented by the integer 1000.

 + + micro_seconds +

Symbolic representation of the time unit + represented by the integer 1000000.

 + + nano_seconds +

Symbolic representation of the time unit + represented by the integer 1000000000.

 + + native +

Symbolic representation of the native time unit + used by the Erlang runtime system.

+ +

The native time unit is determined at + runtime system start, and will remain 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 + native time unit of the old runtime system + instance.

+ +

One can get an approximation of the native + time unit by calling erlang:convert_time_unit(1, + 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.

+ + +

The value of the native time unit gives + you more or less no information at all about the + quality of time values. It sets an upper bound for + the resolution as well as for the precision, but it + gives absolutely no information at all about the + accuracy.

+ + + + + +

The time_unit/0 type may be extended. Use + erlang:convert_time_unit/3 + in order to convert time values between time units.

+ @@ -584,6 +648,22 @@ + + + Convert time unit of a time value + +

Converts the Time value of time unit + FromUnit to the corresponding + ConvertedTime value of time unit + ToUnit. The result is rounded + using the floor function.

+ +

You may lose accuracy and precision when converting + between time units. In order to minimize such loss, collect all + data at native time unit and do the conversion on the end + result.

 + + Compute crc32 (IEEE 802.3) checksum @@ -2191,14 +2271,15 @@ os_prompt% - Return an almost unique reference + Return a unique reference -

Returns an almost unique reference.

-

The returned reference will re-occur after approximately 2^82 - calls; therefore it is unique enough for practical purposes.

- 
-> make_ref().
-#Ref<0.0.0.135>
+

Return a unique + reference. The reference is unique among + connected nodes.

+

Known issue: When a node is restarted multiple + times with the same node name, references created + on a newer node can be mistaken for a reference + created on an older node with the same node name.

 @@ -2499,97 +2580,178 @@ os_prompt% - + + + + + Start monitoring -

The calling process starts monitoring Item which is - an object of type Type.

-

Currently only processes can be monitored, i.e. the only - allowed Type is process, but other types may be - allowed in the future.

-

Item can be:

- - pid() - -

The pid of the process to monitor.

- - {RegName, Node} - -

A tuple consisting of a registered name of a process and - a node name. The process residing on the node Node - with the registered name RegName will be monitored.

- - RegName - -

The process locally registered as RegName will be - monitored.

- - - -

When a process is monitored by registered name, the process - that has the registered name at the time when - monitor/2 is called will be monitored. +

Send a monitor request of type Type to the + entity identified by Item. The caller of + monitor/2 will later be notified by a monitor message on the + 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.

 +

Currently valid Types:

+ + process + +

Monitor the existence of the process identified by + Item. Currently valid + Items in combination with the + process Type:

+ + pid() + +

The process identifier of the process to monitor.

+ + {RegisteredName, Node} + +

A tuple consisting of a registered name of a process and + a node name. The process residing on the node Node + with the registered name {RegisteredName, Node} will + be monitored.

+ + RegisteredName + +

The process locally registered as RegisteredName + will become monitored.

+ + +

When a process is monitored by registered name, the + process that has the registered name at the time when the + monitor request reach its destination will be monitored. The monitor will not be effected, if the registered name is - unregistered.

- -

A 'DOWN' message will be sent to the monitoring - process if Item dies, if Item does not exist, - or if the connection is lost to the node which Item - resides on. A 'DOWN' message has the following pattern:

- -{'DOWN', MonitorRef, Type, Object, Info} -

where MonitorRef and Type are the same as - described above, and:

- - Object - -

A reference to the monitored object:

- - the pid of the monitored process, if Item was - specified as a pid. - {RegName, Node}, if Item was specified as - {RegName, Node}. - {RegName, Node}, if Item was specified as - RegName. Node will in this case be the - name of the local node (node()). - - - Info - -

Either the exit reason of the process, noproc - (non-existing process), or noconnection (no - connection to Node).

- - - -

If/when monitor/2 is extended (e.g. to - handle other item types than process), other - possible values for Object, and Info in the - 'DOWN' message will be introduced.

- -

The monitoring is turned off either when the 'DOWN' - message is sent, or when - demonitor/1 - is called.

-

If an attempt is made to monitor a process on an older node - (where remote process monitoring is not implemented or one - where remote process monitoring by registered name is not - implemented), the call fails with badarg.

-

Making several calls to monitor/2 for the same - Item is not an error; it results in as many, completely - independent, monitorings.

+ unregistered, or unregistered and later registered on another + process.

 +

The monitor is triggered either when the monitored process + terminates, is non existing, or if the connection to it is + lost. In the case the connection to it is lost, we do not know + if it still exist or not. After this type of monitor has been + triggered, the monitor is automatically removed.

+

When the monitor is triggered a 'DOWN' message will + be sent to the monitoring process. A 'DOWN' message has + the following pattern:

+ {'DOWN', MonitorRef, Type, Object, Info} +

where MonitorRef and Type are the same as + described above, and:

+ + Object + +

equals:

+ + Item + If Item was specified by a + pid. + {RegisteredName, Node} + If Item was specified as + RegisteredName, or {RegisteredName, Node} + where Node corresponds to the node that the + monitored process resides on. + + + Info + +

Either the exit reason of the process, noproc + (non-existing process), or noconnection (no + connection to the node where the monitored process + resides).

 + +

The monitoring is turned off either when the 'DOWN' + message is sent, or when + demonitor/1 + is called.

+

If an attempt is made to monitor a process on an older node + (where remote process monitoring is not implemented or one + where remote process monitoring by registered name is not + implemented), the call fails with badarg.

+ +

The format of the 'DOWN' message changed in the 5.2 + version of the emulator (OTP release R9B) for monitor + by registered name. The Object element of + the 'DOWN' message could in earlier versions + sometimes be the pid of the monitored process and sometimes + be the registered name. Now the Object element is + always a tuple consisting of the registered name and + the node name. Processes on new nodes (emulator version 5.2 + or greater) will always get 'DOWN' messages on + the new format even if they are monitoring processes on old + nodes. Processes on old nodes will always get 'DOWN' + messages on the old format.

+ + + time_offset + +

Monitor changes in + time offset + between + Erlang + monotonic time and + Erlang + system time. There is only one valid + Item in combination with the + time_offset Type, namely the atom + clock_service. Note that the atom clock_service is + not the registered name of a process. In this specific + case it serves as an identifier of the runtime system internal + clock service at current runtime system instance.

+ +

The monitor is triggered when the time offset is changed. + This either if the time offset value is changed, or if the + offset is changed from preliminary to final during + finalization + of the time offset when the + 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.

+ +

If the runtime system is in + multi + time warp mode, the time offset will be changed when + the runtime system detects that the + OS system + time has changed. The runtime system will, however, + not detect this immediately when it happens. A task checking + the time offset is scheduled to execute at least once a minute, + so under normal operation this should be detected within a + minute, but during heavy load it might take longer time.

+ +

The monitor will not be automatically removed + after it has been triggered. That is, repeated changes of + the time offset will trigger the monitor repeatedly.

+ +

When the monitor is triggered a 'CHANGE' message will + be sent to the monitoring process. A 'CHANGE' message has + the following pattern:

+ {'CHANGE', MonitorRef, Type, Item, NewTimeOffset} +

where MonitorRef, Type, and + Item are the same as described above, and + NewTimeOffset is the new time offset.

+ +

When the 'CHANGE' message has been received you are + guaranteed not to retrieve the old time offset when calling + erlang:time_offset(). + Note that you may observe the change of the time offset + when calling erlang:time_offset() before you + get the 'CHANGE' message.

+ + + +

Making several calls to monitor/2 for the same + Item and/or Type is not + an error; it results in many, completely independent, + monitorings.

+

The monitor functionality is expected to be extended. That is, + other Types and Items + are expected to be supported in the future.

-

The format of the 'DOWN' message changed in the 5.2 - version of the emulator (OTP release R9B) for monitor by registered name. The Object element of - the 'DOWN' message could in earlier versions - sometimes be the pid of the monitored process and sometimes - be the registered name. Now the Object element is - always a tuple consisting of the registered name and - the node name. Processes on new nodes (emulator version 5.2 - or greater) will always get 'DOWN' messages on - the new format even if they are monitoring processes on old - nodes. Processes on old nodes will always get 'DOWN' - messages on the old format.

+

If/when monitor/2 is extended, other + possible values for Tag, Object, and + Info in the monitor message will be introduced.

 @@ -2639,6 +2801,51 @@ os_prompt% option list is malformed.

+ + + Current Erlang monotonic time + +

Returns the current + Erlang + monotonic time in native + time unit. This + is a monotonically increasing time since some unspecified point in + time.

+ +

This is a + monotonically increasing time, but not a + strictly monotonically increasing + time. That is, consecutive calls to + erlang:monotonic_time/0 may produce the same result.

+ +

Different runtime system instances will use different + unspecified points in time as base for their Erlang monotonic clocks. + That is, it is pointless comparing monotonic times from + 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 + retrieved by calling + erlang:system_info(start_time).

 + + + + + Current Erlang monotonic time + +

Returns the current + Erlang + monotonic time converted + into the Unit passed as argument.

+ +

Same as calling + erlang:convert_time_unit(erlang:monotonic_time(), + native, Unit) + however optimized for commonly used Units.

+ + Stop execution with a given reason @@ -2734,6 +2941,13 @@ os_prompt% Elapsed time since 00:00 GMT +

This function is deprecated! Do not use it! + See the users guide chapter + Time and Time Correction + for more information. Specifically the + Dos and Dont's + section for information on what to use instead of erlang:now/0. +

Returns the tuple {MegaSecs, Secs, MicroSecs} which is the elapsed time since 00:00 GMT, January 1, 1970 (zero hour) on the assumption that the underlying OS supports this. @@ -2746,10 +2960,6 @@ os_prompt%

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.

-

If you do not need the return value to be unique and - monotonically increasing, use - os:timestamp/0 - instead to avoid some overhead.

 @@ -5496,6 +5706,35 @@ ok

Returns the old value of the flag.

 + + + + Finalize the Time Offset + +

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:

+ +

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 + erlang:system_flag(time_offset, finalize) call, or + due to the + no + time warp mode being used.

 + +

volatile is returned, the time offset + cannot be finalized due to the + multi + time warp mode being used.

 + + + @@ -5776,6 +6015,15 @@ ok + + + + + + + + + Information about the system

Returns various information about the current system @@ -6163,6 +6411,57 @@ ok documentation of versions in the system principles guide.

+ os_monotonic_time_source + +

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 + 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 + introduced in the future:

+ + {function, Function} +

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

 + + {clock_id, ClockId} +

This tuple only exist if Function + can be used with different clocks. ClockId + corresponds to the clock identifer 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 retreived from + the OS, OsMonotonicTimeResolution will be + set to the resolution of the time unit of + Functions return value. That is, the actual + resolution may be lower than + OsMonotonicTimeResolution. Also note that + the resolution does not say anything about the + accuracy, and that the precision might not align + with the resolution. You do, however, know that the + precision won't be higher than + OsMonotonicTimeResolution.

 + + {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, OsMonotonicTime} +

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

 + + port_parallelism

Returns the default port parallelism scheduling hint used. For more information see the @@ -6288,6 +6587,11 @@ ok

Returns true if the emulator has been compiled with smp support; otherwise, false.

 + start_time +

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

 system_version

Returns a string containing version number and @@ -6311,12 +6615,64 @@ ok (driver_async()) 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 + at a later time when being finalized. The preliminary time offset + is used during the preliminary phase of the + single + time warp mode.

 + + final +

The time offset is final. This + either due to the use of the + no + time warp mode, or due to the time offset having + been finalized when using the + single + time warp mode.

 + + volatile +

The time offset is volatile. That is, it may + change at any time. This due to the + multi + time warp mode being used.

 + + + time_warp_mode +

Returns a value identifying the + time warp + mode being used:

+ + no_time_warp +

The no + time warp mode is being used.

 + + single_time_warp +

The single + time warp mode is being used.

 + + multi_time_warp +

The multi + time warp mode is being used.

 + + tolerant_timeofday -

Returns whether compensation for sudden changes of system - time is enabled or disabled.

-

See also +c - command line flag.

+

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 @@ -6595,7 +6951,44 @@ ok + + + Current Erlang system time + +

Returns current + Erlang system time + in native + time unit.

+

Calling erlang:system_time() is equivalent to: + erlang:monotonic_time() + + + erlang:time_offset().

+ +

This time is not a monotonically increasing time + in the general case. For more information, see the documentation of + time warp modes in the + ERTS User's Guide.

 + + + + + Current Erlang system time + +

Returns current + Erlang system time + converted into the Unit passed as argument.

+ +

Calling erlang:system_time(Unit) is equivalent to: + erlang:convert_time_unit(erlang:system_time(), + native, Unit).

+ +

This time is not a monotonically increasing time + in the general case. For more information, see the documentation of + time warp modes in the + ERTS User's Guide.

 + + Encode a term to an Erlang external term format binary @@ -6671,6 +7064,88 @@ ok {9,42,44} + + + Current time offset + +

Returns the current time offset between + Erlang monotonic time + and + Erlang system time in + native time unit. + Current time offset added to an Erlang monotonic time gives + corresponding Erlang system time.

+ +

The time offset may or may not change during operation depending + on the time + warp mode used.

+ + +

A change in time offset may be observed at slightly + different points in time by different processes.

+ +

If the runtime system is in + multi + time warp mode, the time offset will be changed when + the runtime system detects that the + OS system + time has changed. The runtime system will, however, + not detect this immediately when it happens. A task checking + the time offset is scheduled to execute at least once a minute, + so under normal operation this should be detected within a + minute, but during heavy load it might take longer time.

+ + + + + + Current time offset + +

Returns the current time offset between + Erlang monotonic time + and + Erlang system time + converted into the Unit passed as argument.

+ +

Same as calling + erlang:convert_time_unit(erlang:time_offset(), native, Unit) + however optimized for commonly used Units.

+ + + + + + Current Erlang System time + +

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 + 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 + the time unit of your choice using + erlang:system_time/1.

+ +

The erlang:timestamp() BIF is equivalent to:

+timestamp() -> + ErlangSystemTime = erlang:system_time(micro_seconds), + MegaSecs = ErlangSystemTime div 1000000000000, + Secs = ErlangSystemTime div 1000000 - MegaSecs*1000000, + MicroSecs = ErlangSystemTime rem 1000000, + {MegaSecs, Secs, MicroSecs}. +

It however use a native implementation which does + not build garbage on the heap and with slightly better + performance.

+ +

This time is not a monotonically increasing time + in the general case. For more information, see the documentation of + time warp modes in the + ERTS User's Guide.

 + + + Tail of a list @@ -7435,6 +7910,100 @@ ok a valid date and time.

 + + + Get a unique integer value + +

Generates and returns an + integer + unique on current runtime system instance. The same as calling + erlang:unique_integer([]).

+ + + + + Get a unique integer value + +

Generates and returns an + integer + unique on current runtime system + instance. The integer is unique in the + sense that this BIF, using the same set of + modifiers, will not return the same integer more + than once on the current runtime system instance. + Each integer value can of course be constructed + by other means.

+ +

By default, i.e. 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. + 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 + returned integers.

+ +

Currently valid Modifiers:

+ + + positive +

Return only positive integers.

+

Note that by passing the positive modifier + you will get heap allocated integers (big-nums) + quicker.

+ + + monotonic +

Return + strictly + monotonically increasing integers + corresponding to creation time. That is, the integer + returned will always be larger than previously + returned integers on the current runtime system + instance.

+

These values can be used when ordering events + on the runtime system instance. That is, if both + X = erlang:unique_integer([monotonic]) and + Y = erlang:unique_integer([monotonic]) are + executed by different processes (or the same + process) on the same runtime system instance and + X < Y we know that X was created + 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 + modifier unless you really need strictly monotonically + increasing values.

 + + + + +

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

+ +

Note that the set of integers returned by + unique_integer/1 using diffrent sets of + Modifiers will overlap. + For example, by calling unique_integer([monotonic]), + and unique_integer([positive, monotonic]) + repeatedly, you will eventually see some integers being + returned by both calls.

 + +

Failures:

+ + badarg + if ModifierList is not a + proper list. + badarg + if Modifier is not a + valid modifier. + + + Remove a link, if there is one, to another process or port -- cgit v1.2.3