Add monotonic_time, system_time and unique_integer to System

[whatyouhide]

Implements #4018.

The implementation is pretty straightforward, I'm just not sure about the docs: should they be more specific? Should they just point to the docs of the functions in the :erlang module?

(also, is :erlang.time_unit ok in the @spec or should I replicate the type in the System module?)

[fishcakez]

The return of this function is spec'ed as integer, not pos_integer.

[whatyouhide]

Oops, right. Good catch!

[fishcakez]

When using the time API I have found convert_time_unit/3 very useful, using it almost every time I've used time. The main reason is that its ideal to use native throughout readings/calculations and then convert to the desired unit at the end. Similarly to convert from a desired unit to native when configuration is read.

[lexmag]

Don't forget to actually inline all of them.

[whatyouhide]

Actually inlined all the functions. We can't use default args with system_time and monotonic_time like @fishcakez suggested because Erlang throws ArgumentErrors for those:

iex> :erlang.system_time(:native)
** (ArgumentError) ...

As for convert_time_unit/3, I think it makes sense, should I go on and add it?

[lexmag]

I think you could move get_stacktrace inlining into this group as well.

[josevalim]

It is ordered alphabetically, so it should be before tuple. :)

[lexmag]

Then this group move there. 😄

[josevalim]

+1 for convert_time_unit

[whatyouhide]

Ok, pushed all the mentioned changes. I removed the explict "see [function] for more information" in the docs as when I say "Inlined by the compiler into fun", fun is linked automatically.

We should be good to go!

[lexmag]

I'm wondering, shall we have erlang:time_offset/0 as well?
It's recommended for use when "Seed Random Number Generation With a Unique Value".

[lexmag]

And more important "Determine Order of Events With Time of the Event".
It might be the only way to do so.

[fishcakez]

@lexmag when would use time_offset and not system_time in those cases?

[lexmag]

@fishcakez to identify the order of events for example, from new time API guide:

Time = erlang:monotonic_time(),
UMI = erlang:unique_integer([monotonic]),
EventTag = {Time, UMI}

And if you are interested in the Erlang system time at the time when the event occurred you can also save the time offset before or after saving the events using erlang:time_offset/0. Erlang monotonic time added with the time offset corresponds to Erlang system time.
If you are executing in a mode where time offset may change and you want to be able to get the actual Erlang system time when the event occurred you can save the time offset as a third element in the tuple (the least significant element when comparing 3-tuples).

Thus it's needed to make {Time, UMI, Offset}.

[lexmag]

You can't use system_time in that case, as offset can "travel" to any "side".

[josevalim]

Let's add time_offset as well as it is related to system_time

[fishcakez]

You can't use system_time in that case, as offset can "travel" to any "side".

I don't follow this bit, can you expand?

[lexmag]

Having this snippet we have proper Order of Events:

Time = erlang:monotonic_time(),
UMI = erlang:unique_integer([monotonic]),
EventTag = {Time, UMI}

but it doesn't really represent time when the event occurred and thus one can use erlang:system_time() instead of erlang:monotonic_time() what is truly wrong because this system_time can perform a time warp.
The proper way is to form {erlang:monotonic_time(), UMI, erlang:system_time()}.
Indeed, in that case system_time should work, but it seems a bit redundant (and I'm afraid error-prone if people confuse the order), the third element could just be an erlang:time_offset().
It looks more explicit to me, and we have one less erlang:monotonic_time() call underneath.

[fishcakez]

Oh sorry, I thought you were saying can not use system_time as third element but you weren't at all.

[fishcakez]

It looks more explicit to me, and we have one less erlang:monotonic_time() call underneath.

I think its less explicit as reason that term is there is so we know the system time and not the offset. Though of course the optimisation is nice and makes good sense. I think we need to work on the docs to explain under each function when it is suitable to use it and with examples showing how to combine with other functions.