From 805f7ea2f2b4e1aeef7326db439ab2b810729f33 Mon Sep 17 00:00:00 2001 From: Paul Sokolovsky Date: Tue, 1 Nov 2016 00:14:12 +0300 Subject: [PATCH] docs/utime: Add docs for ticks_add(), improvements for other ticks_*(). --- docs/library/utime.rst | 52 +++++++++++++++++++++++++++++++++++------- 1 file changed, 44 insertions(+), 8 deletions(-) diff --git a/docs/library/utime.rst b/docs/library/utime.rst index 8fa5cb1759..109c3560cc 100644 --- a/docs/library/utime.rst +++ b/docs/library/utime.rst @@ -89,15 +89,16 @@ Functions 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 + [0 .. `TICKS_MAX`], inclusive, total `TICKS_PERIOD` values. Note 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 + returned 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. + Note: Performing standard mathematical operations (+, -) or relational + operators (<, <=, >, >=) directly on these value will lead to invalid + result. Performing mathematical operations and then passing their results + as arguments to ``ticks_diff()`` or ``ticks_add()`` will also lead to + invalid results from the latter functions. .. function:: ticks_us() @@ -114,7 +115,34 @@ Functions function is intended for very fine benchmarking or very tight real-time loops. Avoid using it in portable code. - Availability: Not every port implement this function. + Availability: Not every port implements this function. + + +.. function:: ticks_add(ticks, delta) + + Offset ticks value by a given number, which can be either positive or negative. + Given a ``ticks`` value, this function allows to calculate ticks value ``delta`` + ticks before or after it, following modular-arithmetic definition of tick values + (see ``ticks_ms()`` above). ``ticks`` parameter must be a direct result of call + to ``tick_ms()``, ``ticks_us()``, ``ticks_cpu()`` functions (or from previous + call to ``ticks_add()``). However, ``delta`` can be an arbitrary integer number + or numeric expression. ``ticks_add()`` is useful for calculating deadlines for + events/tasks. (Note: you must use ``ticks_diff()`` function to work with + deadlines.) + + Examples:: + + # Find out what ticks value there was 100ms ago + print(tick_add(time.ticks_ms(), -100)) + + # Calculate deadline for operation and test for it + deadline = tick_add(time.ticks_ms(), 200) + while ticks_diff(deadline, time.ticks_ms()) > 0: + do_a_little_of_something() + + # Find out TICKS_MAX used by this port + print(tick_add(0, -1)) + .. function:: ticks_diff(ticks1, ticks2) @@ -128,13 +156,21 @@ Functions **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 + `ticks1` occured 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. + Informal rationale of the constraints above: Suppose you are locked in a room with no + means to monitor passing of time except a standard 12-notch clock. Then if you look at + dial-plate now, and don't look again for another 13 hours (e.g., if you fall for a + long sleep), then once you finally look again, it may seem to you that only 1 hour + has passed. To avoid this mistake, just look at the clock regularly. Your application + should do the same. "Too long sleep" metaphor also maps directly to application + behavior: don't let your application run any single task for too long. Run tasks + in steps, and do time-keeping inbetween. ``ticks_diff()`` is designed to accommodate various usage patterns, among them: