@@ -116,59 +116,57 @@ Functions
116116
117117 Availability: Not every port implement this function.
118118
119- .. only :: port_unix or port_pyboard or port_wipy or port_esp8266
120-
121- .. function :: ticks_diff(ticks1, ticks2)
122-
123- Measure ticks difference between values returned from ticks_ms(), ticks_us(), or ticks_cpu()
124- functions. The argument order is the same as for subtraction operator,
125- ``tick_diff(ticks1, ticks2) `` has the same meaning as ``ticks1 - ticks2 ``. However, values returned by
126- ticks_ms(), etc. functions may wrap around, so directly using subtraction on them will
127- produce incorrect result. That is why ticks_diff() is needed, it implements modular
128- (or more specifically, ring) arithmetics to produce correct result even for wrap-around
129- values (as long as they not too distant inbetween, see below). The function returns
130- **signed ** value in the range [`-TICKS_PERIOD/2 ` .. `TICKS_PERIOD/2-1 `] (that's a typical
131- range definition for two's-complement signed binary integers). If the result is negative,
132- it means that `ticks1 ` occured earlier in time than `ticks2 `. Otherwise, it means that
133- `ticks1 ` was after `ticks2 `. This holds `only ` if `ticks1 ` and `ticks2 ` are apart from
134- each other for no more than `TICKS_PERIOD/2-1 ` ticks. If that does not hold, incorrect
135- result will be returned. Specifically, if 2 tick values are apart for `TICKS_PERIOD/2-1 `
136- ticks, that value will be returned by the function. However, if `TICKS_PERIOD/2 ` of
137- real-time ticks has passed between them, the function will return `-TICKS_PERIOD/2 `
138- instead, i.e. result value will wrap around to the negative range of possible values.
139-
140-
141- ``ticks_diff() `` is designed to accommodate various usage patterns, among them:
142-
143- Polling with timeout. In this case, the order of events is known, and you will deal
144- only with positive results of ``ticks_diff() ``::
145-
146- # Wait for GPIO pin to be asserted, but at most 500us
147- start = time.ticks_us()
148- while pin.value() == 0:
149- if time.ticks_diff(time.ticks_us(), start) > 500:
150- raise TimeoutError
151-
152- Scheduling events. In this case, ``ticks_diff() `` result may be negative
153- if an event is overdue::
154-
155- # This code snippet is not optimized
156- now = time.ticks_ms()
157- scheduled_time = task.scheduled_time()
158- if ticks_diff(now, scheduled_time) > 0:
159- print("Too early, let's nap")
160- sleep_ms(ticks_diff(now, scheduled_time))
161- task.run()
162- elif ticks_diff(now, scheduled_time) == 0:
163- print("Right at time!")
164- task.run()
165- elif ticks_diff(now, scheduled_time) < 0:
166- print("Oops, running late, tell task to run faster!")
167- task.run(run_faster=true)
168-
169- Note: Do not pass ``time() `` values to ``ticks_diff() ``, and should use
170- normal mathematical operations on them. But note that ``time() `` may (and will)
171- also overflow. This is known as https://en.wikipedia.org/wiki/Year_2038_problem .
119+ .. function :: ticks_diff(ticks1, ticks2)
120+
121+ Measure ticks difference between values returned from ticks_ms(), ticks_us(), or ticks_cpu()
122+ functions. The argument order is the same as for subtraction operator,
123+ ``tick_diff(ticks1, ticks2) `` has the same meaning as ``ticks1 - ticks2 ``. However, values returned by
124+ ticks_ms(), etc. functions may wrap around, so directly using subtraction on them will
125+ produce incorrect result. That is why ticks_diff() is needed, it implements modular
126+ (or more specifically, ring) arithmetics to produce correct result even for wrap-around
127+ values (as long as they not too distant inbetween, see below). The function returns
128+ **signed ** value in the range [`-TICKS_PERIOD/2 ` .. `TICKS_PERIOD/2-1 `] (that's a typical
129+ range definition for two's-complement signed binary integers). If the result is negative,
130+ it means that `ticks1 ` occured earlier in time than `ticks2 `. Otherwise, it means that
131+ `ticks1 ` was after `ticks2 `. This holds `only ` if `ticks1 ` and `ticks2 ` are apart from
132+ each other for no more than `TICKS_PERIOD/2-1 ` ticks. If that does not hold, incorrect
133+ result will be returned. Specifically, if 2 tick values are apart for `TICKS_PERIOD/2-1 `
134+ ticks, that value will be returned by the function. However, if `TICKS_PERIOD/2 ` of
135+ real-time ticks has passed between them, the function will return `-TICKS_PERIOD/2 `
136+ instead, i.e. result value will wrap around to the negative range of possible values.
137+
138+
139+ ``ticks_diff() `` is designed to accommodate various usage patterns, among them:
140+
141+ Polling with timeout. In this case, the order of events is known, and you will deal
142+ only with positive results of ``ticks_diff() ``::
143+
144+ # Wait for GPIO pin to be asserted, but at most 500us
145+ start = time.ticks_us()
146+ while pin.value() == 0:
147+ if time.ticks_diff(time.ticks_us(), start) > 500:
148+ raise TimeoutError
149+
150+ Scheduling events. In this case, ``ticks_diff() `` result may be negative
151+ if an event is overdue::
152+
153+ # This code snippet is not optimized
154+ now = time.ticks_ms()
155+ scheduled_time = task.scheduled_time()
156+ if ticks_diff(now, scheduled_time) > 0:
157+ print("Too early, let's nap")
158+ sleep_ms(ticks_diff(now, scheduled_time))
159+ task.run()
160+ elif ticks_diff(now, scheduled_time) == 0:
161+ print("Right at time!")
162+ task.run()
163+ elif ticks_diff(now, scheduled_time) < 0:
164+ print("Oops, running late, tell task to run faster!")
165+ task.run(run_faster=true)
166+
167+ Note: Do not pass ``time() `` values to ``ticks_diff() ``, and should use
168+ normal mathematical operations on them. But note that ``time() `` may (and will)
169+ also overflow. This is known as https://en.wikipedia.org/wiki/Year_2038_problem .
172170
173171
174172.. function :: time()
0 commit comments