From 6487aac5977cf470bc6a2cd0964da2850ee38717 Mon Sep 17 00:00:00 2001
From: Rickard Green <rickard@erlang.org>
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.
---
 lib/kernel/doc/src/os.xml | 48 ++++++++++++++++++++++++++++++++++++++++++-----
 1 file changed, 43 insertions(+), 5 deletions(-)

(limited to 'lib/kernel/doc')

diff --git a/lib/kernel/doc/src/os.xml b/lib/kernel/doc/src/os.xml
index 2b57e75023..763bf01cc9 100644
--- a/lib/kernel/doc/src/os.xml
+++ b/lib/kernel/doc/src/os.xml
@@ -128,15 +128,50 @@ DirOut = os:cmd("dir"), % on Win32 platform</code>
 	environment is set using wide character interfaces.</p>
       </desc>
     </func>
+    <func>
+      <name name="system_time" arity="0"/>
+      <fsummary>Current OS system time</fsummary>
+      <desc>
+	<p>Returns current
+	<seealso marker="erts:time_correction#OS_System_Time">OS system time</seealso>
+	in <c>native</c>
+	<seealso marker="erts:erlang#type_time_unit">time unit</seealso>.</p>
+
+	<note><p>This time is <em>not</em> a monotonically increasing time.</p></note>
+      </desc>
+    </func>
+    <func>
+      <name name="system_time" arity="1"/>
+      <fsummary>Current OS system time</fsummary>
+      <desc>
+	<p>Returns current
+	<seealso marker="erts:time_correction#OS_System_Time">OS system time</seealso>
+	converted into the <c><anno>Unit</anno></c> passed as argument.</p>
+
+	<p>Calling <c>os:system_time(<anno>Unit</anno>)</c> is equivalent to: 
+	<seealso marker="erts:erlang#convert_time_unit/3"><c>erlang:convert_time_unit</c></seealso><c>(</c><seealso marker="#system_time/0"><c>os:system_time()</c></seealso><c>,
+	native, <anno>Unit</anno>)</c>.</p>
+
+	<note><p>This time is <em>not</em> a monotonically increasing time.</p></note>
+      </desc>
+    </func>
     <func>
       <name name="timestamp" arity="0"/>
       <type_desc variable="Timestamp">Timestamp = {MegaSecs, Secs, MicroSecs}</type_desc>
-      <fsummary>Returna a timestamp from the OS in the erlang:now/0 format</fsummary>
+      <fsummary>Current OS system time on the erlang:timestamp/0 format</fsummary>
       <desc>
-      <p>Returns a tuple in the same format as <seealso marker="erts:erlang#now/0">erlang:now/0</seealso>. The difference is that this function returns what the operating system thinks (a.k.a. the wall clock time) without any attempts at time correction. The result of two different calls to this function is <em>not</em> guaranteed to be different.</p>
-      <p>The most obvious use for this function is logging. The tuple can be used together with the function <seealso marker="stdlib:calendar#now_to_universal_time/1">calendar:now_to_universal_time/1</seealso> 
-or <seealso marker="stdlib:calendar#now_to_local_time/1">calendar:now_to_local_time/1</seealso> to get calendar time. Using the calendar time together with the <c>MicroSecs</c> part of the return tuple from this function allows you to log timestamps in high resolution and consistent with the time in the rest of the operating system.</p>
-      <p>Example of code formatting a string in the format &quot;DD Mon YYYY HH:MM:SS.mmmmmm&quot;, where DD is the day of month, Mon is the textual month name, YYYY is the year, HH:MM:SS is the time and mmmmmm is the microseconds in six positions:</p>
+      <p>Returns current
+	<seealso marker="erts:time_correction#OS_System_Time">OS system time</seealso>
+        in the same format as <seealso marker="erts:erlang#timestamp/0">erlang:timestamp/0</seealso>.
+	The tuple can be used together with the function
+	<seealso marker="stdlib:calendar#now_to_universal_time/1">calendar:now_to_universal_time/1</seealso> 
+        or <seealso marker="stdlib:calendar#now_to_local_time/1">calendar:now_to_local_time/1</seealso> to
+        get calendar time. Using the calendar time together with the <c>MicroSecs</c> part of the return
+        tuple from this function allows you to log timestamps in high resolution and consistent with the
+        time in the rest of the operating system.</p>
+      <p>Example of code formatting a string in the format &quot;DD Mon YYYY HH:MM:SS.mmmmmm&quot;, where
+         DD is the day of month, Mon is the textual month name, YYYY is the year, HH:MM:SS is the time and
+         mmmmmm is the microseconds in six positions:</p>
 <code>
 -module(print_time).
 -export([format_utc_timestamp/0]).
@@ -155,6 +190,9 @@ format_utc_timestamp() ->
 1> <input>io:format("~s~n",[print_time:format_utc_timestamp()]).</input>
 29 Apr 2009  9:55:30.051711
 </pre>
+       <p>OS system time can also be retreived by
+	<c><seealso marker="#system_time/0"><c>os:system_time/0</c></seealso></c>,
+	and <seealso marker="#system_time/1"><c>os:system_time/1</c></seealso>.</p>
       </desc>
     </func>
     <func>
-- 
cgit v1.2.3