diff options
| -rw-r--r-- | docs/library/utime.rst | 104 |
1 files changed, 51 insertions, 53 deletions
diff --git a/docs/library/utime.rst b/docs/library/utime.rst index 7a73234d48..8fa5cb1759 100644 --- a/docs/library/utime.rst +++ b/docs/library/utime.rst @@ -116,59 +116,57 @@ Functions Availability: Not every port implement this function. -.. only:: port_unix or port_pyboard or port_wipy or port_esp8266 - - .. function:: ticks_diff(ticks1, ticks2) - - 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(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:: ticks_diff(ticks1, ticks2) + + 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(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() |