Ambiguous use of TICKS_MAX in time.ticks_diff and time.ticks_add given the time.ticks_ms has different resolution from _us and _cpu and it could cover different ranges in time and values

[Petrox]

https://docs.micropython.org/en/v1.20.0/library/time.html

Scenario:

user uses ticks_ms() reads the docs about TICKS_MAX and the rolling over part... learns that he has to use ticks_diff() and ticks_add() to work with the values properly.

BUT
ticks_us() is described as: "Just like ticks_ms() above, but in microseconds."

The issue is, that it is not clarified if TICKS_MAX is the same (or not) for ticks_ms than ticks_us (maybe it should be TICKS_MAX_MS and TICKS_MAX_US and TICKS_MAX_CPU).

If the TICKS_MAX is the same for us, ms and cpu variants that means the maximum time interval these functions handle are wildly different, and this needs to be clarified. (Also there should be a lower bound to this say it won't roll over for "at least a second" to design the application for)

If the TICKS_MAX is different for ticks_ms() and ticks_us() (and ticks_cpu()) then there should be a different ticks_diff_ms() and ticks_add_ms() and ticks_diff_us() to properly handle the difference.

Based on the current text in the docs one could ASSUME that TICKS_MAX is the same for all three resolutions available, but it is not explicitly declared. Also this might not be true in the future. So maybe adding ticks_add_us() and ticks_diff_us() would be beneficial even if they are the same in all current implementations.

[dpgeorge]

When these ticks functions were added, it was a design decision to make them all (ms, us, cpu) have the same TICKS_MAX, ie the same roll over value. Then you can use ticks_add() and ticks_diff() for all units.

The docs can be clarified on this point.

[massimosala]

The docs can be clarified on this point.

Surely it will be useful to improve the docs.

Question: is it possible to expose TICKS_MAX ?

time.TICKS_MAX

Users have to know it, because ticks_diff can account for one rollover, not more.
Not knowing TICKS_MAX, it is impossible to write reliable code dealing with long time spans.

[peterhinch]

Long time spans can be handled using time.time() along with the ticks methods.

[massimosala]

Long time spans can be handled using time.time() along with the ticks methods.

We are talking about two different clocks:

• ticks, monotonic
• time, not monotonic

Yes, it is possible to handle long time spans with two clocks and a more complex logic to test and maintain.

In many cases it is sufficient to know TICKS_MAX.
If, for example, my appliance reboots every night and I know TICKS_MAX covers a longer time span, I am safe using ticks without any additional logic.

I have worked on other embedded systems and the monotonic clock rollover is always clearly documented.

I really dont' understand: are there any problem exposing its value?

If it is the old adagio "one more attribute consumes memory", at least its value should be documented in the official docs.

No hidden magic, please!

[Petrox]

Even if specific values are not available we would like to get some min constraints. Eg. There's not much use of n 8bit nanosec counter, if if rolls over every ms multiple times. There should be a design pillar that "if I check this value at least once every 5 seconds, I'll be safe". There is no such guarantee, my code could break any time in the next release or 8 releases next year. Thank you.

…

On Fri, Jun 23, 2023, 11:40 massimosala ***@***.***> wrote: Long time spans can be handled using time.time() along with the ticks methods. We are talking about two different clocks: - ticks, monotonic - time, not monotonic Yes, it is possible to handle long time spans with two clocks and *a more complex logic* to test and maintain. In many cases it is sufficient to know TICKS_MAX. If, for example, my appliance reboots every night and I know TICKS_MAX covers a longer time span, I am safe using ticks without any additional logic. I have worked on other embedded systems and the monotonic clock rollover is always clearly documented. I really dont' understand: are there any problem exposing its value? If it is the old adagio "one more attribute consumes memory", at least *its value should be documented in the official docs.* No hidden magic, please! — Reply to this email directly, view it on GitHub <#11840 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAXFKXJ7SKLN76CEL4OJR2LXMVQCJANCNFSM6AAAAAAZPJF5ZA> . You are receiving this because you authored the thread.Message ID: ***@***.***>

[robert-hh]

From the documentation of the module time at https://docs.micropython.org/en/latest/library/time.html?highlight=ticks_max

# Find out TICKS_MAX used by this port
import time
TICKS_MAX = time.ticks_add(0, -1)

[massimosala]

From the documentation of the module time at https://docs.micropython.org/en/latest/library/time.html?highlight=ticks_max

# Find out TICKS_MAX used by this port
import time
TICKS_MAX = time.ticks_add(0, -1)

Thanks Robert.
I hope this tip will be included in the official docs.

This and other goodies that flow from the discussions would be instantly visible to everyone if we had this:
#11844

[robert-hh]

I hope this tip will be included in the official docs.

That's where it is already.

[massimosala]

I hope this tip will be included in the official docs.

That's where it is already.

You are right, I miss it because I didn't read time.ticks_add

Since TICKS_MAX is explained in the ticks_ms documentation and the examples under ticks_add show the use of both ticks_add and ticks_diff, I believe the examples are more visible when moved under ticks_ms.