From d60ad5cf5356b7600ed53365216405c546fea299 Mon Sep 17 00:00:00 2001 From: Paul Sokolovsky Date: Mon, 31 Oct 2016 00:17:56 +0300 Subject: [PATCH] docs/utime: Describe new semantics of ticks_diff() (signed ring arithmetics). --- docs/library/utime.rst | 74 +++++++++++++++++++++++++++++++++++------- 1 file changed, 62 insertions(+), 12 deletions(-) diff --git a/docs/library/utime.rst b/docs/library/utime.rst index 3eff4cd756..7a73234d48 100644 --- a/docs/library/utime.rst +++ b/docs/library/utime.rst @@ -82,9 +82,22 @@ Functions .. function:: ticks_ms() - Returns an increasing millisecond counter with arbitrary reference point, - that wraps after some (unspecified) value. The value should be treated as - opaque, suitable for use only with ticks_diff(). + Returns an increasing millisecond counter with an arbitrary reference point, + that wraps around after some value. This value is not explicitly exposed, + but we will refer to it as `TICKS_MAX` to simplify discussion. Period of + the values is `TICKS_PERIOD = TICKS_MAX + 1`. `TICKS_PERIOD` is guaranteed + to be a power of two, but otherwise may differ from port to port. The same + period value is used for all of ticks_ms(), ticks_us(), ticks_cpu() functions + (for simplicity). Thus, these functions will return a value in range + [0 .. `TICKS_MAX`], inclusive, total `TICKS_PERIOD` values. Not that only + non-negative values are used. For the most part, you should treat values + return by these functions as opaque. The only operations available for them + are ``ticks_diff()`` and ``ticks_add()`` functions described below. + + Note: Performing standard mathematical operations (+, -) on these value + will lead to invalid result. Performing such operations and then passing + results as arguments to ``ticks_diff()`` or ``ticks_add()`` will also lead to + invalid result. .. function:: ticks_us() @@ -105,22 +118,59 @@ Functions .. only:: port_unix or port_pyboard or port_wipy or port_esp8266 - .. function:: ticks_diff(old, new) + .. function:: ticks_diff(ticks1, ticks2) - Measure period between consecutive calls to ticks_ms(), ticks_us(), or ticks_cpu(). - The value returned by these functions may wrap around at any time, so directly - subtracting them is not supported. ticks_diff() should be used instead. "old" value should - actually precede "new" value in time, or result is undefined. This function should not be - used to measure arbitrarily long periods of time (because ticks_*() functions wrap around - and usually would have short period). The expected usage pattern is implementing event - polling with timeout:: + Measure ticks difference between values returned from ticks_ms(), ticks_us(), or ticks_cpu() + functions. The argument order is the same as for subtraction operator, + ``tick_diff(ticks1, ticks2)`` has the same meaning as ``ticks1 - ticks2``. However, values returned by + ticks_ms(), etc. functions may wrap around, so directly using subtraction on them will + produce incorrect result. That is why ticks_diff() is needed, it implements modular + (or more specifically, ring) arithmetics to produce correct result even for wrap-around + values (as long as they not too distant inbetween, see below). The function returns + **signed** value in the range [`-TICKS_PERIOD/2` .. `TICKS_PERIOD/2-1`] (that's a typical + range definition for two's-complement signed binary integers). If the result is negative, + it means that `ticks1` occured earlier in time than `ticks2`. Otherwise, it means that + `ticks1` was after `ticks2`. This holds `only` if `ticks1` and `ticks2` are apart from + each other for no more than `TICKS_PERIOD/2-1` ticks. If that does not hold, incorrect + result will be returned. Specifically, if 2 tick values are apart for `TICKS_PERIOD/2-1` + ticks, that value will be returned by the function. However, if `TICKS_PERIOD/2` of + real-time ticks has passed between them, the function will return `-TICKS_PERIOD/2` + instead, i.e. result value will wrap around to the negative range of possible values. + + + ``ticks_diff()`` is designed to accommodate various usage patterns, among them: + + Polling with timeout. In this case, the order of events is known, and you will deal + only with positive results of ``ticks_diff()``:: # Wait for GPIO pin to be asserted, but at most 500us start = time.ticks_us() while pin.value() == 0: - if time.ticks_diff(start, time.ticks_us()) > 500: + if time.ticks_diff(time.ticks_us(), start) > 500: raise TimeoutError + Scheduling events. In this case, ``ticks_diff()`` result may be negative + if an event is overdue:: + + # This code snippet is not optimized + now = time.ticks_ms() + scheduled_time = task.scheduled_time() + if ticks_diff(now, scheduled_time) > 0: + print("Too early, let's nap") + sleep_ms(ticks_diff(now, scheduled_time)) + task.run() + elif ticks_diff(now, scheduled_time) == 0: + print("Right at time!") + task.run() + elif ticks_diff(now, scheduled_time) < 0: + print("Oops, running late, tell task to run faster!") + task.run(run_faster=true) + + Note: Do not pass ``time()`` values to ``ticks_diff()``, and should use + normal mathematical operations on them. But note that ``time()`` may (and will) + also overflow. This is known as https://en.wikipedia.org/wiki/Year_2038_problem . + + .. function:: time() Returns the number of seconds, as an integer, since the Epoch, assuming that underlying