File tree

1 file changed

+59
-3
lines changed

1 file changed

+59
-3
lines changed
Original file line numberDiff line numberDiff line change
@@ -19,13 +19,14 @@
1919
7. [Use in synchronous code](./SCHEDULE.md#7-use-in-synchronous-code) If you really must.
2020
7.1 [Initialisation](./SCHEDULE.md#71-initialisation)__
2121
8. [The simulate script](./SCHEDULE.md#8-the-simulate-script) Rapidly test sequences.
22+
9. [Design note](./SCHEDULE.md#9-design-note) Notes on use under an OS.
2223

2324
Release note:
2425
11th Dec 2023 Document astronomy module, allowing scheduling based on Sun and
25-
Moon rise and set times.
26-
23rd Nov 2023 Add asynchronous iterator interface.
26+
Moon rise and set times.
27+
23rd Nov 2023 Add asynchronous iterator interface.
2728
3rd April 2023 Fix issue #100. Where an iterable is passed to `secs`, triggers
28-
must now be at least 10s apart (formerly 2s).
29+
must now be at least 10s apart (formerly 2s).
2930

3031
##### [Tutorial](./TUTORIAL.md#contents)
3132
##### [Main V3 README](../README.md)
@@ -285,6 +286,9 @@ and duplicates when they go back. Scheduling those times will fail. A solution
285286
is to avoid scheduling the times in your region where this occurs (01.00.00 to
286287
02.00.00 in March and October here).
287288

289+
It is believed that in other respects DST is handled correctly by the OS: see
290+
[Design note](./SCHEDULE.md#9-design-note).
291+
288292
##### [Top](./SCHEDULE.md#0-contents)
289293

290294
## 4.5 Callback interface
@@ -546,3 +550,55 @@ the value of system time when the delay ends. In this instance the start of a
546550
sequence is delayed to ensure that the first trigger occurs at 01:00.
547551

548552
##### [Top](./SCHEDULE.md#0-contents)
553+
554+
# 9. Design note
555+
556+
This module is primarily intended for use on a microcontroller, where the time
557+
source is a hardware RTC. This is usually set to local time and does not change
558+
for daylight saving time (DST). Changing the system time while running `asyncio`
559+
code is not recommended.
560+
561+
A [question was raised](https://.com/peterhinch/micropython-async/pull/126)
562+
regarding the behaviour of the module when running under the Unix build - in
563+
particular whether the module's use of `time.localtime` is correct, because
564+
`.localtime` changes when DST is invoked. To test whether a problem exists, an
565+
attempt was made to write a script whose behaviour under Unix differed from that
566+
on a microcontroller. The latter has no concept of DST or timezone (TZ) so can
567+
be assumed to be free of such bugs. Unless such a reproducer can be found, it
568+
seems that usage under the Unix build should be correct.
569+
570+
The following test script outputs the time in seconds between two fixed times
571+
separated by two months, the period being chosen to cross a DST boundary here in
572+
the UK. It passed under the following conditions:
573+
574+
* On a Pyboard.
575+
* On an ESP32.
576+
* On Unix MicroPython.
577+
* On CPython.
578+
* On the Unix build with my laptop's location set to California. Reported time
579+
changed by -7hrs.
580+
* On CPython in California.
581+
582+
The conclusion is that the OS ensures that DST related errors do not occur.
583+
584+
```py
585+
from time import mktime, gmtime, localtime
586+
from sys import implementation
587+
cpython = implementation.name == 'cpython'
588+
if cpython:
589+
from time import struct_time
590+
591+
start = [2024, 9, 5, 11, 49, 2, 3, 249, 1]
592+
sept = round(mktime(struct_time(start))) if cpython else mktime(start)
593+
594+
end = start[:]
595+
end[1] += 2 # Same time + 2months Crosses DST boundary in the UK
596+
597+
november = round(mktime(struct_time(end))) if cpython else mktime(end)
598+
print(november - sept)
599+
600+
if november - sept == 5270400:
601+
print('PASS')
602+
else:
603+
print('FAIL')
604+
```

0 commit comments

Comments
 (0)