Skip to content
GitLab
Explore
Sign in
Register
Primary navigation
Search or go to…
Project
M
micropython
Manage
Activity
Members
Labels
Plan
Issues
Issue boards
Milestones
Wiki
Code
Merge requests
Repository
Branches
Commits
Tags
Repository graph
Compare revisions
Snippets
Build
Pipelines
Jobs
Pipeline schedules
Artifacts
Deploy
Releases
Container registry
Model registry
Operate
Environments
Monitor
Incidents
Service Desk
Analyze
Value stream analytics
Contributor analytics
CI/CD analytics
Repository analytics
Model experiments
Help
Help
Support
GitLab documentation
Compare GitLab plans
GitLab community forum
Contribute to GitLab
Provide feedback
Terms and privacy
Keyboard shortcuts
?
Snippets
Groups
Projects
This is an archived project. Repository and other project resources are read-only.
Show more breadcrumbs
card10
micropython
Commits
d60ad5cf
Commit
d60ad5cf
authored
8 years ago
by
Paul Sokolovsky
Browse files
Options
Downloads
Patches
Plain Diff
docs/utime: Describe new semantics of ticks_diff() (signed ring arithmetics).
parent
153665f1
Branches
Branches containing commit
No related tags found
No related merge requests found
Changes
1
Show whitespace changes
Inline
Side-by-side
Showing
1 changed file
docs/library/utime.rst
+62
-12
62 additions, 12 deletions
docs/library/utime.rst
with
62 additions
and
12 deletions
docs/library/utime.rst
+
62
−
12
View file @
d60ad5cf
...
...
@@ -82,9 +82,22 @@ Functions
.. function:: ticks_ms()
Returns an increasing millisecond counter with arbitrary reference point,
that wraps after some (unspecified) value. The value should be treated as
opaque, suitable for use only with ticks_diff().
Returns an increasing millisecond counter with an arbitrary reference point,
that wraps around after some value. This value is not explicitly exposed,
but we will refer to it as `TICKS_MAX` to simplify discussion. Period of
the values is `TICKS_PERIOD = TICKS_MAX + 1`. `TICKS_PERIOD` is guaranteed
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
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
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.
.. function:: ticks_us()
...
...
@@ -105,22 +118,59 @@ Functions
.. only:: port_unix or port_pyboard or port_wipy or port_esp8266
.. function:: ticks_diff(
old, new
)
.. function:: ticks_diff(
ticks1, ticks2
)
Measure period between consecutive calls to ticks_ms(), ticks_us(), or ticks_cpu().
The value returned by these functions may wrap around at any time, so directly
subtracting them is not supported. ticks_diff() should be used instead. "old" value should
actually precede "new" value in time, or result is undefined. This function should not be
used to measure arbitrarily long periods of time (because ticks_*() functions wrap around
and usually would have short period). The expected usage pattern is implementing event
polling with timeout::
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(
start,
time.ticks_us()) > 500:
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()
Returns the number of seconds, as an integer, since the Epoch, assuming that underlying
...
...
This diff is collapsed.
Click to expand it.
Preview
0%
Loading
Try again
or
attach a new file
.
Cancel
You are about to add
0
people
to the discussion. Proceed with caution.
Finish editing this message first!
Save comment
Cancel
Please
register
or
sign in
to comment