onboarding_due.py 3.8 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899
  1. """The desktop's boot question, answered once: is onboarding due, and can something carry it.
  2. ``onboarding.state`` asks it on every launch, and a cold first boot answering it live competes
  3. with every other boot thread for the same provider reads. The serve boot works it out on its own
  4. thread (:func:`begin_boot`), and ``onboarding.state`` reads the cached answer, waiting a bounded
  5. time for a boot computation still in flight. Every writer that can move the answer calls
  6. :func:`invalidate`: the root ``onboarding.run`` (``onboarding_run.set_run``), the OS user's marker
  7. (``install_state``) and the setup record (``free_tier_bootstrap``). The next reader then computes
  8. live once and caches that. A *stamp* the caller passes (the files the answer reads) catches edits
  9. no writer in this process saw, such as a key typed into ``.env`` by hand. It is taken before and
  10. after each computation, and an answer is cached only when the files held still in between: one
  11. computed while a key landed would otherwise sit under the new stamp. The computation itself lives
  12. with its caller (``tui_gateway``), which owns the default-profile scope it runs in.
  13. """
  14. from __future__ import annotations
  15. import threading
  16. from collections.abc import Callable, Hashable
  17. # The desktop's first question waits this long for the boot computation before answering live.
  18. BOOT_WAIT_SECONDS = 8.0
  19. # The boot's first computation can write a config skeleton itself, so its files move once.
  20. _BOOT_ATTEMPTS = 2
  21. Due = dict[str, bool]
  22. Stamp = Callable[[], Hashable]
  23. _lock = threading.Lock()
  24. _value: Due | None = None
  25. _value_stamp: Hashable = None
  26. _generation = 0
  27. _boot_done: threading.Event | None = None
  28. def begin_boot(stamp: Stamp = lambda: None) -> Callable[[Callable[[], Due]], None]:
  29. """Mark a boot computation as in flight (readers wait for it from now on) and return the call
  30. that finishes it: ``finish(compute)`` runs *compute* and caches its answer, unless a writer
  31. invalidated meanwhile or the files never held still."""
  32. global _boot_done
  33. done = threading.Event()
  34. with _lock:
  35. _boot_done = done
  36. def finish(compute: Callable[[], Due]) -> None:
  37. try:
  38. for _ in range(_BOOT_ATTEMPTS):
  39. with _lock:
  40. generation = _generation
  41. seen = stamp()
  42. value = compute()
  43. if _store(value, generation, seen, stamp()):
  44. return
  45. finally:
  46. done.set()
  47. return finish
  48. def read(compute: Callable[[], Due], *, stamp: Stamp = lambda: None, wait: float = BOOT_WAIT_SECONDS) -> Due:
  49. """The cached answer; a boot computation in flight is waited for (bounded), and with nothing
  50. cached, or files moved since (*stamp*), *compute* answers live and is cached."""
  51. done = _boot_done
  52. if done is not None:
  53. done.wait(wait)
  54. seen = stamp()
  55. with _lock:
  56. if _value is not None and _value_stamp == seen:
  57. return dict(_value)
  58. generation = _generation
  59. value = compute()
  60. _store(value, generation, seen, stamp())
  61. return dict(value)
  62. def invalidate() -> None:
  63. global _value, _generation
  64. with _lock:
  65. _value = None
  66. _generation += 1
  67. def reset_for_tests() -> None:
  68. global _boot_done
  69. invalidate()
  70. with _lock:
  71. _boot_done = None
  72. def _store(value: Due, generation: int, before: Hashable, after: Hashable) -> bool:
  73. """Cache *value*, computed between the stamps *before* and *after*; True when it was cached."""
  74. global _value, _value_stamp
  75. if before != after: # a file moved mid-computation: the answer may predate it
  76. return False
  77. with _lock:
  78. if generation != _generation: # a writer that landed meanwhile wins over this computation
  79. return False
  80. _value, _value_stamp = dict(value), after
  81. return True