# © Copyright 2021-2022, Scott Gasch
"""Several helpers to keep track of internal state via periodic
-polling. :class:StateTracker expects to be invoked periodically to
-maintain state whereas the others (:class:AutomaticStateTracker and
-:class:WaitableAutomaticStateTracker) automatically update themselves
+polling. :class:`StateTracker` expects to be invoked periodically to
+maintain state whereas the others (:class:`AutomaticStateTracker` and
+:class:`WaitableAutomaticStateTracker`) automatically update themselves
and, optionally, expose an event for client code to wait on state
changes.
"""
Args:
update_id: the string you passed to the c'tor as a key in
- the update_ids_to_update_secs dict. :meth:update will
+ the update_ids_to_update_secs dict. :meth:`update` will
only be invoked on the shoulder, at most, every update_secs
seconds.
def heartbeat(self, *, force_all_updates_to_run: bool = False) -> None:
"""Invoke this method to cause the StateTracker instance to identify
and invoke any overdue updates based on the schedule passed to
- the c'tor. In the base :class:StateTracker class, this method must
+ the c'tor. In the base :class:`StateTracker` class, this method must
be invoked manually by a thread from external code. Other subclasses
are available that create their own updater threads (see below).
class AutomaticStateTracker(StateTracker):
- """Just like :class:StateTracker but you don't need to pump the
- :meth:heartbeat method periodically because we create a background
- thread that manages periodic calling. You must call :meth:shutdown,
+ """Just like :class:`StateTracker` but you don't need to pump the
+ :meth:`heartbeat` method periodically because we create a background
+ thread that manages periodic calling. You must call :meth:`shutdown`,
though, in order to terminate the update thread.
"""
@background_thread
def pace_maker(self, should_terminate: threading.Event) -> None:
- """Entry point for a background thread to own calling :meth:heartbeat
+ """Entry point for a background thread to own calling :meth:`heartbeat`
at regular intervals so that the main thread doesn't need to
do so.
"""
override_sleep_delay: By default, this class determines
how long the background thread should sleep between
- automatic invocations to :meth:heartbeat based on the
+ automatic invocations to :meth:`heartbeat` based on the
period of each update type in update_ids_to_update_secs.
If this argument is non-None, it overrides this computation
and uses this period as the sleep in the background thread.
override_sleep_delay: By default, this class determines
how long the background thread should sleep between
- automatic invocations to :meth:heartbeat based on the
+ automatic invocations to :meth:`heartbeat` based on the
period of each update type in update_ids_to_update_secs.
If this argument is non-None, it overrides this computation
and uses this period as the sleep in the background thread.