Commit 805f7ea2 authored by Paul Sokolovsky's avatar Paul Sokolovsky
Browse files

docs/utime: Add docs for ticks_add(), improvements for other ticks_*().

parent 8679d9e6
......@@ -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:
......
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment