fix: keep event order, measure delays on the monotonic clock, cancel by marking (#665)

Three fixes to how the engines order, time and cancel events, and a
refactor that removes every suppression from the modules they touch.

Events due at the same moment kept their order only by chance: both
queues are PriorityQueues ordered by execution_time alone, so triggers
stamped alike came out in heap order. TriggerData now numbers each
trigger as it is created and compares that number after execution_time.

Delays were measured on the wall clock, so a step of time.time() held
or hastened every due time. Stamps and due checks now use
time.monotonic().

Cancelling a delayed event filtered the list behind the heap, which is
not always a heap afterwards, and dropped the trigger's future, so a
coroutine awaiting it on the async engine was never answered.
cancel_event() now marks each trigger sent with the send_id as
cancelled and answers its future with None; the queue drops cancelled
triggers from its head. EventQueue.pop_due() pops the head only once it
is due, under the queue's mutex, so a trigger waiting on its delay never
leaves the queue and a cancel from another thread always finds it.

No type: ignore, noqa, pragma: no cover or pragma: no branch is left in
engines/base.py, engines/sync.py, engines/async_.py or statemachine.py.
The methods only the sync engine implements synchronously moved from
BaseEngine to SyncEngine, each processing loop is split into its
macrostep, the external events and one external event, and the code
the pragmas hid is either removed as unreachable or covered by a test.

Release notes in docs/releases/3.2.2.md.

Co-authored-by: Fernando Macedo <fgmacedo@gmail.com>
Signed-off-by: Fernando Macedo <fgmacedo@gmail.com>

Author: JMerrill-Fairness

docs/releases/3.2.2.md

@@ -76,6 +76,43 @@ Reported by [@Dolecor](https://github.com/Dolecor).
 
 [#643](https://github.com/fgmacedo/python-statemachine/issues/643).
 
+### Events due at the same moment kept their order only by chance
+
+Both event queues are priority queues ordered by each trigger's due time, and triggers due at
+the same time came out in no particular order. A clock coarse enough to stamp two events alike
+could run them out of the order they were sent or raised: twenty events raised in one callback,
+all stamped with the same time, ran as `0, 2, 6, 14, 19, 18, ...`. Each trigger now also holds
+the order it was created in, and triggers due at the same moment run in that order, on both
+engines and both queues.
+
+[#665](https://github.com/fgmacedo/python-statemachine/pull/665).
+
+### Cancelling a delayed event could disorder the others and strand its caller
+
+`cancel_event()` removed a trigger by filtering the list behind the queue's heap, and a filtered
+heap is not always a heap. The triggers left could then run out of due order: of ten delayed
+events due from 10 to 90 ms, cancelling the first left the one due at 50 ms running before the
+one due at 40 ms. The trigger's future went with it, so on the async engine a coroutine
+awaiting the cancelled event's `send()` was never answered.
+
+A cancelled trigger now stays where it is, marked as cancelled, and is dropped when it reaches
+the head of the queue, without the processing loop waiting for its due time. A coroutine
+awaiting it gets `None` as soon as it is cancelled. A trigger waiting on its delay also stays
+in the queue while the loop checks the clock, so a `cancel_event()` from another thread always
+finds it.
+
+[#665](https://github.com/fgmacedo/python-statemachine/pull/665).
+
+### Delays measured on the wall clock
+
+Every trigger was stamped with `time.time()` plus its delay, and the processing loop held a
+trigger until `time.time()` reached its stamp. A step of the wall clock, from a time sync or a
+change of the system time, moved every due time with it: stepped back, it held even an event
+sent with no delay until the clock caught up; stepped forward, it ran delayed events early.
+Delays are now measured on `time.monotonic()`, which no setting of the wall clock moves.
+
+[#665](https://github.com/fgmacedo/python-statemachine/pull/665).
+
 ### `delay` and `internal` dropped from an explicit `Event`
 
 `Event(dark.to(lit), delay=50)` rebuilt the event without its `delay`, so

docs/statechart.md

@@ -113,6 +113,8 @@ sm.send("timeout", delay=5000, send_id="my_timeout")
 sm.cancel_event("my_timeout")
 ```
 
+On the async engine, a coroutine awaiting the `send()` of a cancelled event gets `None`.
+
 ```{note}
 The delay is **blocking** in the sync engine — the processing loop sleeps until the
 delay elapses, holding the calling thread. In the async engine, delays are scheduled