Skip to content
GitLab
Menu
Projects
Groups
Snippets
/
Help
Help
Support
Community forum
Keyboard shortcuts
?
Submit feedback
Sign in
Toggle navigation
Menu
Open sidebar
TASTE
uPython-mirror
Commits
805f7ea2
Commit
805f7ea2
authored
Nov 01, 2016
by
Paul Sokolovsky
Browse files
docs/utime: Add docs for ticks_add(), improvements for other ticks_*().
parent
8679d9e6
Changes
1
Hide whitespace changes
Inline
Side-by-side
docs/library/utime.rst
View file @
805f7ea2
...
...
@@ -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. Not
e
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
return
ed
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:
...
...
Write
Preview
Supports
Markdown
0%
Try again
or
attach a new file
.
Attach a file
Cancel
You are about to add
0
people
to the discussion. Proceed with caution.
Finish editing this message first!
Cancel
Please
register
or
sign in
to comment