docs/utime: Add docs for ticks_add(), improvements for other ticks_*().
This commit is contained in:
parent
8679d9e6a6
commit
805f7ea2f2
|
@ -89,15 +89,16 @@ Functions
|
||||||
to be a power of two, but otherwise may differ from port to port. The same
|
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
|
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
|
(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
|
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.
|
are ``ticks_diff()`` and ``ticks_add()`` functions described below.
|
||||||
|
|
||||||
Note: Performing standard mathematical operations (+, -) on these value
|
Note: Performing standard mathematical operations (+, -) or relational
|
||||||
will lead to invalid result. Performing such operations and then passing
|
operators (<, <=, >, >=) directly on these value will lead to invalid
|
||||||
results as arguments to ``ticks_diff()`` or ``ticks_add()`` will also lead to
|
result. Performing mathematical operations and then passing their results
|
||||||
invalid result.
|
as arguments to ``ticks_diff()`` or ``ticks_add()`` will also lead to
|
||||||
|
invalid results from the latter functions.
|
||||||
|
|
||||||
.. function:: ticks_us()
|
.. function:: ticks_us()
|
||||||
|
|
||||||
|
@ -114,7 +115,34 @@ Functions
|
||||||
function is intended for very fine benchmarking or very tight real-time loops.
|
function is intended for very fine benchmarking or very tight real-time loops.
|
||||||
Avoid using it in portable code.
|
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)
|
.. 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
|
**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,
|
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
|
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
|
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`
|
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
|
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`
|
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.
|
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:
|
``ticks_diff()`` is designed to accommodate various usage patterns, among them:
|
||||||
|
|
||||||
|
|
Loading…
Reference in New Issue