babase

426class AccountV2Handle:
427    """Handle for interacting with a V2 account.
428
429    This class supports the 'with' statement, which is how it is
430    used with some operations such as cloud messaging.
431    """
432
433    accountid: str
434    tag: str
435    workspacename: str | None
436    workspaceid: str | None
437    logins: dict[LoginType, LoginInfo]
438
439    def __enter__(self) -> None:
440        """Support for "with" statement.
441
442        This allows cloud messages to be sent on our behalf.
443        """
444
445    def __exit__(self, exc_type: Any, exc_value: Any, traceback: Any) -> Any:
446        """Support for "with" statement.
447
448        This allows cloud messages to be sent on our behalf.
449        """

 26class AccountV2Subsystem:
 27    """Subsystem for modern account handling in the app.
 28
 29    Category: **App Classes**
 30
 31    Access the single shared instance of this class at 'ba.app.plus.accounts'.
 32    """
 33
 34    def __init__(self) -> None:
 35        from babase._login import LoginAdapterGPGS, LoginAdapterGameCenter
 36
 37        # Whether or not everything related to an initial login
 38        # (or lack thereof) has completed. This includes things like
 39        # workspace syncing. Completion of this is what flips the app
 40        # into 'running' state.
 41        self._initial_sign_in_completed = False
 42
 43        self._kicked_off_workspace_load = False
 44
 45        self.login_adapters: dict[LoginType, LoginAdapter] = {}
 46
 47        self._implicit_signed_in_adapter: LoginAdapter | None = None
 48        self._implicit_state_changed = False
 49        self._can_do_auto_sign_in = True
 50
 51        adapter: LoginAdapter
 52        if _babase.using_google_play_game_services():
 53            adapter = LoginAdapterGPGS()
 54            self.login_adapters[adapter.login_type] = adapter
 55        if _babase.using_game_center():
 56            adapter = LoginAdapterGameCenter()
 57            self.login_adapters[adapter.login_type] = adapter
 58
 59    def on_app_loading(self) -> None:
 60        """Should be called at standard on_app_loading time."""
 61
 62        for adapter in self.login_adapters.values():
 63            adapter.on_app_loading()
 64
 65    def have_primary_credentials(self) -> bool:
 66        """Are credentials currently set for the primary app account?
 67
 68        Note that this does not mean these credentials are currently valid;
 69        only that they exist. If/when credentials are validated, the 'primary'
 70        account handle will be set.
 71        """
 72        raise NotImplementedError('This should be overridden.')
 73
 74    @property
 75    def primary(self) -> AccountV2Handle | None:
 76        """The primary account for the app, or None if not logged in."""
 77        return self.do_get_primary()
 78
 79    def on_primary_account_changed(
 80        self, account: AccountV2Handle | None
 81    ) -> None:
 82        """Callback run after the primary account changes.
 83
 84        Will be called with None on log-outs and when new credentials
 85        are set but have not yet been verified.
 86        """
 87        assert _babase.in_logic_thread()
 88
 89        # Currently don't do anything special on sign-outs.
 90        if account is None:
 91            return
 92
 93        # If this new account has a workspace, update it and ask to be
 94        # informed when that process completes.
 95        if account.workspaceid is not None:
 96            assert account.workspacename is not None
 97            if (
 98                not self._initial_sign_in_completed
 99                and not self._kicked_off_workspace_load
100            ):
101                self._kicked_off_workspace_load = True
102                _babase.app.workspaces.set_active_workspace(
103                    account=account,
104                    workspaceid=account.workspaceid,
105                    workspacename=account.workspacename,
106                    on_completed=self._on_set_active_workspace_completed,
107                )
108            else:
109                # Don't activate workspaces if we've already told the game
110                # that initial-log-in is done or if we've already kicked
111                # off a workspace load.
112                _babase.screenmessage(
113                    f'\'{account.workspacename}\''
114                    f' will be activated at next app launch.',
115                    color=(1, 1, 0),
116                )
117                _babase.getsimplesound('error').play()
118            return
119
120        # Ok; no workspace to worry about; carry on.
121        if not self._initial_sign_in_completed:
122            self._initial_sign_in_completed = True
123            _babase.app.on_initial_sign_in_complete()
124
125    def on_active_logins_changed(self, logins: dict[LoginType, str]) -> None:
126        """Should be called when logins for the active account change."""
127
128        for adapter in self.login_adapters.values():
129            adapter.set_active_logins(logins)
130
131    def on_implicit_sign_in(
132        self, login_type: LoginType, login_id: str, display_name: str
133    ) -> None:
134        """An implicit sign-in happened (called by native layer)."""
135        from babase._login import LoginAdapter
136
137        assert _babase.in_logic_thread()
138
139        with _babase.ContextRef.empty():
140            self.login_adapters[login_type].set_implicit_login_state(
141                LoginAdapter.ImplicitLoginState(
142                    login_id=login_id, display_name=display_name
143                )
144            )
145
146    def on_implicit_sign_out(self, login_type: LoginType) -> None:
147        """An implicit sign-out happened (called by native layer)."""
148        assert _babase.in_logic_thread()
149        with _babase.ContextRef.empty():
150            self.login_adapters[login_type].set_implicit_login_state(None)
151
152    def on_no_initial_primary_account(self) -> None:
153        """Callback run if the app has no primary account after launch.
154
155        Either this callback or on_primary_account_changed will be called
156        within a few seconds of app launch; the app can move forward
157        with the startup sequence at that point.
158        """
159        if not self._initial_sign_in_completed:
160            self._initial_sign_in_completed = True
161            _babase.app.on_initial_sign_in_complete()
162
163    @staticmethod
164    def _hashstr(val: str) -> str:
165        md5 = hashlib.md5()
166        md5.update(val.encode())
167        return md5.hexdigest()
168
169    def on_implicit_login_state_changed(
170        self,
171        login_type: LoginType,
172        state: LoginAdapter.ImplicitLoginState | None,
173    ) -> None:
174        """Called when implicit login state changes.
175
176        Login systems that tend to sign themselves in/out in the
177        background are considered implicit. We may choose to honor or
178        ignore their states, allowing the user to opt for other login
179        types even if the default implicit one can't be explicitly
180        logged out or otherwise controlled.
181        """
182        from babase._language import Lstr
183
184        assert _babase.in_logic_thread()
185
186        cfg = _babase.app.config
187        cfgkey = 'ImplicitLoginStates'
188        cfgdict = _babase.app.config.setdefault(cfgkey, {})
189
190        # Store which (if any) adapter is currently implicitly signed
191        # in. Making the assumption there will only ever be one implicit
192        # adapter at a time; may need to revisit this logic if that
193        # changes.
194        prev_state = cfgdict.get(login_type.value)
195        if state is None:
196            self._implicit_signed_in_adapter = None
197            new_state = cfgdict[login_type.value] = None
198        else:
199            self._implicit_signed_in_adapter = self.login_adapters[login_type]
200            new_state = cfgdict[login_type.value] = self._hashstr(
201                state.login_id
202            )
203
204            # Special case: if the user is already signed in but not
205            # with this implicit login, let them know that the 'Welcome
206            # back FOO' they likely just saw is not actually accurate.
207            if (
208                self.primary is not None
209                and not self.login_adapters[login_type].is_back_end_active()
210            ):
211                service_str: Lstr | None
212                if login_type is LoginType.GPGS:
213                    service_str = Lstr(resource='googlePlayText')
214                elif login_type is LoginType.GAME_CENTER:
215                    # Note: Apparently Game Center is just called 'Game
216                    # Center' in all languages. Can revisit if not true.
217                    # https://developer.apple.com/forums/thread/725779
218                    service_str = Lstr(value='Game Center')
219                elif login_type is LoginType.EMAIL:
220                    # Not possible; just here for exhaustive coverage.
221                    service_str = None
222                else:
223                    assert_never(login_type)
224                if service_str is not None:
225                    _babase.apptimer(
226                        2.0,
227                        tpartial(
228                            _babase.screenmessage,
229                            Lstr(
230                                resource='notUsingAccountText',
231                                subs=[
232                                    ('${ACCOUNT}', state.display_name),
233                                    ('${SERVICE}', service_str),
234                                ],
235                            ),
236                            (1, 0.5, 0),
237                        ),
238                    )
239
240        cfg.commit()
241
242        # We want to respond any time the implicit state changes;
243        # generally this means the user has explicitly signed in/out or
244        # switched accounts within that back-end.
245        if prev_state != new_state:
246            if DEBUG_LOG:
247                logging.debug(
248                    'AccountV2: Implicit state changed (%s -> %s);'
249                    ' will update app sign-in state accordingly.',
250                    prev_state,
251                    new_state,
252                )
253            self._implicit_state_changed = True
254
255        # We may want to auto-sign-in based on this new state.
256        self._update_auto_sign_in()
257
258    def on_cloud_connectivity_changed(self, connected: bool) -> None:
259        """Should be called with cloud connectivity changes."""
260        del connected  # Unused.
261        assert _babase.in_logic_thread()
262
263        # We may want to auto-sign-in based on this new state.
264        self._update_auto_sign_in()
265
266    def do_get_primary(self) -> AccountV2Handle | None:
267        """Internal - should be overridden by subclass."""
268        raise NotImplementedError('This should be overridden.')
269
270    def set_primary_credentials(self, credentials: str | None) -> None:
271        """Set credentials for the primary app account."""
272        raise NotImplementedError('This should be overridden.')
273
274    def _update_auto_sign_in(self) -> None:
275        plus = _babase.app.plus
276        assert plus is not None
277
278        # If implicit state has changed, try to respond.
279        if self._implicit_state_changed:
280            if self._implicit_signed_in_adapter is None:
281                # If implicit back-end has signed out, we follow suit
282                # immediately; no need to wait for network connectivity.
283                if DEBUG_LOG:
284                    logging.debug(
285                        'AccountV2: Signing out as result'
286                        ' of implicit state change...',
287                    )
288                plus.accounts.set_primary_credentials(None)
289                self._implicit_state_changed = False
290
291                # Once we've made a move here we don't want to
292                # do any more automatic stuff.
293                self._can_do_auto_sign_in = False
294
295            else:
296                # Ok; we've got a new implicit state. If we've got
297                # connectivity, let's attempt to sign in with it.
298                # Consider this an 'explicit' sign in because the
299                # implicit-login state change presumably was triggered
300                # by some user action (signing in, signing out, or
301                # switching accounts via the back-end). NOTE: should
302                # test case where we don't have connectivity here.
303                if plus.cloud.is_connected():
304                    if DEBUG_LOG:
305                        logging.debug(
306                            'AccountV2: Signing in as result'
307                            ' of implicit state change...',
308                        )
309                    self._implicit_signed_in_adapter.sign_in(
310                        self._on_explicit_sign_in_completed,
311                        description='implicit state change',
312                    )
313                    self._implicit_state_changed = False
314
315                    # Once we've made a move here we don't want to
316                    # do any more automatic stuff.
317                    self._can_do_auto_sign_in = False
318
319        if not self._can_do_auto_sign_in:
320            return
321
322        # If we're not currently signed in, we have connectivity, and
323        # we have an available implicit login, auto-sign-in with it once.
324        # The implicit-state-change logic above should keep things
325        # mostly in-sync, but that might not always be the case due to
326        # connectivity or other issues. We prefer to keep people signed
327        # in as a rule, even if there are corner cases where this might
328        # not be what they want (A user signing out and then restarting
329        # may be auto-signed back in).
330        connected = plus.cloud.is_connected()
331        signed_in_v1 = plus.get_v1_account_state() == 'signed_in'
332        signed_in_v2 = plus.accounts.have_primary_credentials()
333        if (
334            connected
335            and not signed_in_v1
336            and not signed_in_v2
337            and self._implicit_signed_in_adapter is not None
338        ):
339            if DEBUG_LOG:
340                logging.debug(
341                    'AccountV2: Signing in due to on-launch-auto-sign-in...',
342                )
343            self._can_do_auto_sign_in = False  # Only ATTEMPT once
344            self._implicit_signed_in_adapter.sign_in(
345                self._on_implicit_sign_in_completed, description='auto-sign-in'
346            )
347
348    def _on_explicit_sign_in_completed(
349        self,
350        adapter: LoginAdapter,
351        result: LoginAdapter.SignInResult | Exception,
352    ) -> None:
353        """A sign-in has completed that the user asked for explicitly."""
354        from babase._language import Lstr
355
356        del adapter  # Unused.
357
358        plus = _babase.app.plus
359        assert plus is not None
360
361        # Make some noise on errors since the user knows a
362        # sign-in attempt is happening in this case (the 'explicit' part).
363        if isinstance(result, Exception):
364            # We expect the occasional communication errors;
365            # Log a full exception for anything else though.
366            if not isinstance(result, CommunicationError):
367                logging.warning(
368                    'Error on explicit accountv2 sign in attempt.',
369                    exc_info=result,
370                )
371
372            # For now just show 'error'. Should do better than this.
373            _babase.screenmessage(
374                Lstr(resource='internal.signInErrorText'),
375                color=(1, 0, 0),
376            )
377            _babase.getsimplesound('error').play()
378
379            # Also I suppose we should sign them out in this case since
380            # it could be misleading to be still signed in with the old
381            # account.
382            plus.accounts.set_primary_credentials(None)
383            return
384
385        plus.accounts.set_primary_credentials(result.credentials)
386
387    def _on_implicit_sign_in_completed(
388        self,
389        adapter: LoginAdapter,
390        result: LoginAdapter.SignInResult | Exception,
391    ) -> None:
392        """A sign-in has completed that the user didn't ask for explicitly."""
393        plus = _babase.app.plus
394        assert plus is not None
395
396        del adapter  # Unused.
397
398        # Log errors but don't inform the user; they're not aware of this
399        # attempt and ignorance is bliss.
400        if isinstance(result, Exception):
401            # We expect the occasional communication errors;
402            # Log a full exception for anything else though.
403            if not isinstance(result, CommunicationError):
404                logging.warning(
405                    'Error on implicit accountv2 sign in attempt.',
406                    exc_info=result,
407                )
408            return
409
410        # If we're still connected and still not signed in,
411        # plug in the credentials we got. We want to be extra cautious
412        # in case the user has since explicitly signed in since we
413        # kicked off.
414        connected = plus.cloud.is_connected()
415        signed_in_v1 = plus.get_v1_account_state() == 'signed_in'
416        signed_in_v2 = plus.accounts.have_primary_credentials()
417        if connected and not signed_in_v1 and not signed_in_v2:
418            plus.accounts.set_primary_credentials(result.credentials)
419
420    def _on_set_active_workspace_completed(self) -> None:
421        if not self._initial_sign_in_completed:
422            self._initial_sign_in_completed = True
423            _babase.app.on_initial_sign_in_complete()

89class ActivityNotFoundError(NotFoundError):
90    """Exception raised when an expected bascenev1.Activity does not exist.
91
92    Category: **Exception Classes**
93    """

82class ActorNotFoundError(NotFoundError):
83    """Exception raised when an expected actor does not exist.
84
85    Category: **Exception Classes**
86    """

  51class App:
  52    """A class for high level app functionality and state.
  53
  54    Category: **App Classes**
  55
  56    Use babase.app to access the single shared instance of this class.
  57
  58    Note that properties not documented here should be considered internal
  59    and subject to change without warning.
  60    """
  61
  62    # pylint: disable=too-many-public-methods
  63
  64    # A few things defined as non-optional values but not actually
  65    # available until the app starts.
  66    plugins: PluginSubsystem
  67    lang: LanguageSubsystem
  68    health_monitor: AppHealthMonitor
  69
  70    # How long we allow shutdown tasks to run before killing them.
  71    # Currently the entire app hard-exits if shutdown takes 10 seconds,
  72    # so we need to keep it under that.
  73    SHUTDOWN_TASK_TIMEOUT_SECONDS = 5
  74
  75    class State(Enum):
  76        """High level state the app can be in."""
  77
  78        # The app has not yet begun starting and should not be used in
  79        # any way.
  80        NOT_STARTED = 0
  81
  82        # The native layer is spinning up its machinery (screens,
  83        # renderers, etc.). Nothing should happen in the Python layer
  84        # until this completes.
  85        NATIVE_BOOTSTRAPPING = 1
  86
  87        # Python app subsystems are being inited but should not yet
  88        # interact or do any work.
  89        INITING = 2
  90
  91        # Python app subsystems are inited and interacting, but the app
  92        # has not yet embarked on a high level course of action. It is
  93        # doing initial account logins, workspace & asset downloads,
  94        # etc.
  95        LOADING = 3
  96
  97        # All pieces are in place and the app is now doing its thing.
  98        RUNNING = 4
  99
 100        # Used on platforms such as mobile where the app basically needs
 101        # to shut down while backgrounded. In this state, all event
 102        # loops are suspended and all graphics and audio must cease
 103        # completely. Be aware that the suspended state can be entered
 104        # from any other state including NATIVE_BOOTSTRAPPING and
 105        # SHUTTING_DOWN.
 106        SUSPENDED = 5
 107
 108        # The app is shutting down. This process may involve sending
 109        # network messages or other things that can take up to a few
 110        # seconds, so ideally graphics and audio should remain
 111        # functional (with fades or spinners or whatever to show
 112        # something is happening).
 113        SHUTTING_DOWN = 6
 114
 115        # The app has completed shutdown. Any code running here should
 116        # be basically immediate.
 117        SHUTDOWN_COMPLETE = 7
 118
 119    class DefaultAppModeSelector(AppModeSelector):
 120        """Decides which AppModes to use to handle AppIntents.
 121
 122        This default version is generated by the project updater based
 123        on the 'default_app_modes' value in the projectconfig.
 124
 125        It is also possible to modify app mode selection behavior by
 126        setting app.mode_selector to an instance of a custom
 127        AppModeSelector subclass. This is a good way to go if you are
 128        modifying app behavior dynamically via a plugin instead of
 129        statically in a spinoff project.
 130        """
 131
 132        @override
 133        def app_mode_for_intent(
 134            self, intent: AppIntent
 135        ) -> type[AppMode] | None:
 136            # pylint: disable=cyclic-import
 137
 138            # __DEFAULT_APP_MODE_SELECTION_BEGIN__
 139            # This section generated by batools.appmodule; do not edit.
 140
 141            # Ask our default app modes to handle it.
 142            # (generated from 'default_app_modes' in projectconfig).
 143            import bascenev1
 144            import babase
 145
 146            for appmode in [
 147                bascenev1.SceneV1AppMode,
 148                babase.EmptyAppMode,
 149            ]:
 150                if appmode.can_handle_intent(intent):
 151                    return appmode
 152
 153            return None
 154
 155            # __DEFAULT_APP_MODE_SELECTION_END__
 156
 157    def __init__(self) -> None:
 158        """(internal)
 159
 160        Do not instantiate this class. You can access the single shared
 161        instance of it through various high level packages: 'babase.app',
 162        'bascenev1.app', 'bauiv1.app', etc.
 163        """
 164
 165        # Hack for docs-generation: we can be imported with dummy modules
 166        # instead of our actual binary ones, but we don't function.
 167        if os.environ.get('BA_RUNNING_WITH_DUMMY_MODULES') == '1':
 168            return
 169
 170        self.env: babase.Env = _babase.Env()
 171        self.state = self.State.NOT_STARTED
 172
 173        # Default executor which can be used for misc background
 174        # processing. It should also be passed to any additional asyncio
 175        # loops we create so that everything shares the same single set
 176        # of worker threads.
 177        self.threadpool = ThreadPoolExecutor(
 178            thread_name_prefix='baworker',
 179            initializer=self._thread_pool_thread_init,
 180        )
 181
 182        self.meta = MetadataSubsystem()
 183        self.net = NetworkSubsystem()
 184        self.workspaces = WorkspaceSubsystem()
 185        self.components = AppComponentSubsystem()
 186        self.stringedit = StringEditSubsystem()
 187        self.devconsole = DevConsoleSubsystem()
 188
 189        # This is incremented any time the app is backgrounded or
 190        # foregrounded; can be a simple way to determine if network data
 191        # should be refreshed/etc.
 192        self.fg_state = 0
 193
 194        self._subsystems: list[AppSubsystem] = []
 195        self._native_bootstrapping_completed = False
 196        self._init_completed = False
 197        self._meta_scan_completed = False
 198        self._native_start_called = False
 199        self._native_suspended = False
 200        self._native_shutdown_called = False
 201        self._native_shutdown_complete_called = False
 202        self._initial_sign_in_completed = False
 203        self._called_on_initing = False
 204        self._called_on_loading = False
 205        self._called_on_running = False
 206        self._subsystem_registration_ended = False
 207        self._pending_apply_app_config = False
 208        self._asyncio_loop: asyncio.AbstractEventLoop | None = None
 209        self._asyncio_tasks: set[asyncio.Task] = set()
 210        self._asyncio_timer: babase.AppTimer | None = None
 211        self._config: babase.AppConfig | None = None
 212        self._pending_intent: AppIntent | None = None
 213        self._intent: AppIntent | None = None
 214        self._mode: AppMode | None = None
 215        self._mode_selector: babase.AppModeSelector | None = None
 216        self._shutdown_task: asyncio.Task[None] | None = None
 217        self._shutdown_tasks: list[Coroutine[None, None, None]] = [
 218            self._wait_for_shutdown_suppressions(),
 219            self._fade_and_shutdown_graphics(),
 220            self._fade_and_shutdown_audio(),
 221        ]
 222        self._pool_thread_count = 0
 223
 224        # We hold a lock while lazy-loading our subsystem properties so
 225        # we don't spin up any subsystem more than once, but the lock is
 226        # recursive so that the subsystems can instantiate other
 227        # subsystems.
 228        self._subsystem_property_lock = RLock()
 229        self._subsystem_property_data: dict[str, AppSubsystem | bool] = {}
 230
 231    def postinit(self) -> None:
 232        """Called after we've been inited and assigned to babase.app.
 233
 234        Anything that accesses babase.app as part of its init process
 235        must go here instead of __init__.
 236        """
 237
 238        # Hack for docs-generation: We can be imported with dummy
 239        # modules instead of our actual binary ones, but we don't
 240        # function.
 241        if os.environ.get('BA_RUNNING_WITH_DUMMY_MODULES') == '1':
 242            return
 243
 244        self.lang = LanguageSubsystem()
 245        self.plugins = PluginSubsystem()
 246
 247    @property
 248    def active(self) -> bool:
 249        """Whether the app is currently front and center.
 250
 251        This will be False when the app is hidden, other activities
 252        are covering it, etc. (depending on the platform).
 253        """
 254        return _babase.app_is_active()
 255
 256    @property
 257    def asyncio_loop(self) -> asyncio.AbstractEventLoop:
 258        """The logic thread's asyncio event loop.
 259
 260        This allow async tasks to be run in the logic thread.
 261
 262        Generally you should call App.create_async_task() to schedule
 263        async code to run instead of using this directly. That will
 264        handle retaining the task and logging errors automatically.
 265        Only schedule tasks onto asyncio_loop yourself when you intend
 266        to hold on to the returned task and await its results. Releasing
 267        the task reference can lead to subtle bugs such as unreported
 268        errors and garbage-collected tasks disappearing before their
 269        work is done.
 270
 271        Note that, at this time, the asyncio loop is encapsulated
 272        and explicitly stepped by the engine's logic thread loop and
 273        thus things like asyncio.get_running_loop() will unintuitively
 274        *not* return this loop from most places in the logic thread;
 275        only from within a task explicitly created in this loop.
 276        Hopefully this situation will be improved in the future with a
 277        unified event loop.
 278        """
 279        assert _babase.in_logic_thread()
 280        assert self._asyncio_loop is not None
 281        return self._asyncio_loop
 282
 283    def create_async_task(
 284        self, coro: Coroutine[Any, Any, T], *, name: str | None = None
 285    ) -> None:
 286        """Create a fully managed async task.
 287
 288        This will automatically retain and release a reference to the task
 289        and log any exceptions that occur in it. If you need to await a task
 290        or otherwise need more control, schedule a task directly using
 291        App.asyncio_loop.
 292        """
 293        assert _babase.in_logic_thread()
 294
 295        # Hold a strong reference to the task until it is done.
 296        # Otherwise it is possible for it to be garbage collected and
 297        # disappear midway if the caller does not hold on to the
 298        # returned task, which seems like a great way to introduce
 299        # hard-to-track bugs.
 300        task = self.asyncio_loop.create_task(coro, name=name)
 301        self._asyncio_tasks.add(task)
 302        task.add_done_callback(self._on_task_done)
 303
 304    def _on_task_done(self, task: asyncio.Task) -> None:
 305        # Report any errors that occurred.
 306        try:
 307            exc = task.exception()
 308            if exc is not None:
 309                logging.error(
 310                    "Error in async task '%s'.", task.get_name(), exc_info=exc
 311                )
 312        except Exception:
 313            logging.exception('Error reporting async task error.')
 314
 315        self._asyncio_tasks.remove(task)
 316
 317    @property
 318    def config(self) -> babase.AppConfig:
 319        """The babase.AppConfig instance representing the app's config state."""
 320        assert self._config is not None
 321        return self._config
 322
 323    @property
 324    def mode_selector(self) -> babase.AppModeSelector:
 325        """Controls which app-modes are used for handling given intents.
 326
 327        Plugins can override this to change high level app behavior and
 328        spinoff projects can change the default implementation for the
 329        same effect.
 330        """
 331        if self._mode_selector is None:
 332            raise RuntimeError(
 333                'mode_selector cannot be used until the app reaches'
 334                ' the running state.'
 335            )
 336        return self._mode_selector
 337
 338    @mode_selector.setter
 339    def mode_selector(self, selector: babase.AppModeSelector) -> None:
 340        self._mode_selector = selector
 341
 342    def _get_subsystem_property(
 343        self, ssname: str, create_call: Callable[[], AppSubsystem | None]
 344    ) -> AppSubsystem | None:
 345
 346        # Quick-out: if a subsystem is present, just return it; no
 347        # locking necessary.
 348        val = self._subsystem_property_data.get(ssname)
 349        if val is not None:
 350            if val is False:
 351                # False means subsystem is confirmed as unavailable.
 352                return None
 353            if val is not True:
 354                # A subsystem has been set. Return it.
 355                return val
 356
 357        # Anything else (no val present or val True) requires locking.
 358        with self._subsystem_property_lock:
 359            val = self._subsystem_property_data.get(ssname)
 360            if val is not None:
 361                if val is False:
 362                    # False means confirmed as not present.
 363                    return None
 364                if val is True:
 365                    # True means this property is already being loaded,
 366                    # and the fact that we're holding the lock means
 367                    # we're doing the loading, so this is a dependency
 368                    # loop. Not good.
 369                    raise RuntimeError(
 370                        f'Subsystem dependency loop detected for {ssname}'
 371                    )
 372                # Must be an instantiated subsystem. Noice.
 373                return val
 374
 375            # Ok, there's nothing here for it. Instantiate and set it
 376            # while we hold the lock. Set a placeholder value of True
 377            # while we load so we can error if something we're loading
 378            # tries to recursively load us.
 379            self._subsystem_property_data[ssname] = True
 380
 381            # Do our one attempt to create the singleton.
 382            val = create_call()
 383            self._subsystem_property_data[ssname] = (
 384                False if val is None else val
 385            )
 386
 387        return val
 388
 389    # __FEATURESET_APP_SUBSYSTEM_PROPERTIES_BEGIN__
 390    # This section generated by batools.appmodule; do not edit.
 391
 392    @property
 393    def classic(self) -> ClassicSubsystem | None:
 394        """Our classic subsystem (if available)."""
 395        return self._get_subsystem_property(
 396            'classic', self._create_classic_subsystem
 397        )  # type: ignore
 398
 399    @staticmethod
 400    def _create_classic_subsystem() -> ClassicSubsystem | None:
 401        # pylint: disable=cyclic-import
 402        try:
 403            from baclassic import ClassicSubsystem
 404
 405            return ClassicSubsystem()
 406        except ImportError:
 407            return None
 408        except Exception:
 409            logging.exception('Error importing baclassic.')
 410            return None
 411
 412    @property
 413    def plus(self) -> PlusSubsystem | None:
 414        """Our plus subsystem (if available)."""
 415        return self._get_subsystem_property(
 416            'plus', self._create_plus_subsystem
 417        )  # type: ignore
 418
 419    @staticmethod
 420    def _create_plus_subsystem() -> PlusSubsystem | None:
 421        # pylint: disable=cyclic-import
 422        try:
 423            from baplus import PlusSubsystem
 424
 425            return PlusSubsystem()
 426        except ImportError:
 427            return None
 428        except Exception:
 429            logging.exception('Error importing baplus.')
 430            return None
 431
 432    @property
 433    def ui_v1(self) -> UIV1Subsystem:
 434        """Our ui_v1 subsystem (always available)."""
 435        return self._get_subsystem_property(
 436            'ui_v1', self._create_ui_v1_subsystem
 437        )  # type: ignore
 438
 439    @staticmethod
 440    def _create_ui_v1_subsystem() -> UIV1Subsystem:
 441        # pylint: disable=cyclic-import
 442
 443        from bauiv1 import UIV1Subsystem
 444
 445        return UIV1Subsystem()
 446
 447    # __FEATURESET_APP_SUBSYSTEM_PROPERTIES_END__
 448
 449    def register_subsystem(self, subsystem: AppSubsystem) -> None:
 450        """Called by the AppSubsystem class. Do not use directly."""
 451
 452        # We only allow registering new subsystems if we've not yet
 453        # reached the 'running' state. This ensures that all subsystems
 454        # receive a consistent set of callbacks starting with
 455        # on_app_running().
 456
 457        if self._subsystem_registration_ended:
 458            raise RuntimeError(
 459                'Subsystems can no longer be registered at this point.'
 460            )
 461        self._subsystems.append(subsystem)
 462
 463    def add_shutdown_task(self, coro: Coroutine[None, None, None]) -> None:
 464        """Add a task to be run on app shutdown.
 465
 466        Note that shutdown tasks will be canceled after
 467        App.SHUTDOWN_TASK_TIMEOUT_SECONDS if they are still running.
 468        """
 469        if (
 470            self.state is self.State.SHUTTING_DOWN
 471            or self.state is self.State.SHUTDOWN_COMPLETE
 472        ):
 473            stname = self.state.name
 474            raise RuntimeError(
 475                f'Cannot add shutdown tasks with current state {stname}.'
 476            )
 477        self._shutdown_tasks.append(coro)
 478
 479    def run(self) -> None:
 480        """Run the app to completion.
 481
 482        Note that this only works on builds where Ballistica manages
 483        its own event loop.
 484        """
 485        _babase.run_app()
 486
 487    def threadpool_submit_no_wait(self, call: Callable[[], Any]) -> None:
 488        """Submit a call to the app threadpool where result is not needed.
 489
 490        Normally, doing work in a thread-pool involves creating a future
 491        and waiting for its result, which is an important step because it
 492        propagates any Exceptions raised by the submitted work. When the
 493        result in not important, however, this call can be used. The app
 494        will log any exceptions that occur.
 495        """
 496        fut = self.threadpool.submit(call)
 497        fut.add_done_callback(self._threadpool_no_wait_done)
 498
 499    def set_intent(self, intent: AppIntent) -> None:
 500        """Set the intent for the app.
 501
 502        Intent defines what the app is trying to do at a given time.
 503        This call is asynchronous; the intent switch will happen in the
 504        logic thread in the near future. If set_intent is called
 505        repeatedly before the change takes place, the final intent to be
 506        set will be used.
 507        """
 508
 509        # Mark this one as pending. We do this synchronously so that the
 510        # last one marked actually takes effect if there is overlap
 511        # (doing this in the bg thread could result in race conditions).
 512        self._pending_intent = intent
 513
 514        # Do the actual work of calcing our app-mode/etc. in a bg thread
 515        # since it may block for a moment to load modules/etc.
 516        self.threadpool_submit_no_wait(tpartial(self._set_intent, intent))
 517
 518    def push_apply_app_config(self) -> None:
 519        """Internal. Use app.config.apply() to apply app config changes."""
 520        # To be safe, let's run this by itself in the event loop.
 521        # This avoids potential trouble if this gets called mid-draw or
 522        # something like that.
 523        self._pending_apply_app_config = True
 524        _babase.pushcall(self._apply_app_config, raw=True)
 525
 526    def on_native_start(self) -> None:
 527        """Called by the native layer when the app is being started."""
 528        assert _babase.in_logic_thread()
 529        assert not self._native_start_called
 530        self._native_start_called = True
 531        self._update_state()
 532
 533    def on_native_bootstrapping_complete(self) -> None:
 534        """Called by the native layer once its ready to rock."""
 535        assert _babase.in_logic_thread()
 536        assert not self._native_bootstrapping_completed
 537        self._native_bootstrapping_completed = True
 538        self._update_state()
 539
 540    def on_native_suspend(self) -> None:
 541        """Called by the native layer when the app is suspended."""
 542        assert _babase.in_logic_thread()
 543        assert not self._native_suspended  # Should avoid redundant calls.
 544        self._native_suspended = True
 545        self._update_state()
 546
 547    def on_native_unsuspend(self) -> None:
 548        """Called by the native layer when the app suspension ends."""
 549        assert _babase.in_logic_thread()
 550        assert self._native_suspended  # Should avoid redundant calls.
 551        self._native_suspended = False
 552        self._update_state()
 553
 554    def on_native_shutdown(self) -> None:
 555        """Called by the native layer when the app starts shutting down."""
 556        assert _babase.in_logic_thread()
 557        self._native_shutdown_called = True
 558        self._update_state()
 559
 560    def on_native_shutdown_complete(self) -> None:
 561        """Called by the native layer when the app is done shutting down."""
 562        assert _babase.in_logic_thread()
 563        self._native_shutdown_complete_called = True
 564        self._update_state()
 565
 566    def on_native_active_changed(self) -> None:
 567        """Called by the native layer when the app active state changes."""
 568        assert _babase.in_logic_thread()
 569        if self._mode is not None:
 570            self._mode.on_app_active_changed()
 571
 572    def read_config(self) -> None:
 573        """(internal)"""
 574        from babase._appconfig import read_app_config
 575
 576        self._config = read_app_config()
 577
 578    def handle_deep_link(self, url: str) -> None:
 579        """Handle a deep link URL."""
 580        from babase._language import Lstr
 581
 582        assert _babase.in_logic_thread()
 583
 584        appname = _babase.appname()
 585        if url.startswith(f'{appname}://code/'):
 586            code = url.replace(f'{appname}://code/', '')
 587            if self.classic is not None:
 588                self.classic.accounts.add_pending_promo_code(code)
 589        else:
 590            try:
 591                _babase.screenmessage(
 592                    Lstr(resource='errorText'), color=(1, 0, 0)
 593                )
 594                _babase.getsimplesound('error').play()
 595            except ImportError:
 596                pass
 597
 598    def on_initial_sign_in_complete(self) -> None:
 599        """Called when initial sign-in (or lack thereof) completes.
 600
 601        This normally gets called by the plus subsystem. The
 602        initial-sign-in process may include tasks such as syncing
 603        account workspaces or other data so it may take a substantial
 604        amount of time.
 605        """
 606        assert _babase.in_logic_thread()
 607        assert not self._initial_sign_in_completed
 608
 609        # Tell meta it can start scanning extra stuff that just showed
 610        # up (namely account workspaces).
 611        self.meta.start_extra_scan()
 612
 613        self._initial_sign_in_completed = True
 614        self._update_state()
 615
 616    def _set_intent(self, intent: AppIntent) -> None:
 617        # This should be happening in a bg thread.
 618        assert not _babase.in_logic_thread()
 619        try:
 620            # Ask the selector what app-mode to use for this intent.
 621            if self.mode_selector is None:
 622                raise RuntimeError('No AppModeSelector set.')
 623            modetype = self.mode_selector.app_mode_for_intent(intent)
 624
 625            # NOTE: Since intents are somewhat high level things, should
 626            # we do some universal thing like a screenmessage saying
 627            # 'The app cannot handle that request' on failure?
 628
 629            if modetype is None:
 630                raise RuntimeError(
 631                    f'No app-mode found to handle app-intent'
 632                    f' type {type(intent)}.'
 633                )
 634
 635            # Make sure the app-mode the selector gave us *actually*
 636            # supports the intent.
 637            if not modetype.can_handle_intent(intent):
 638                raise RuntimeError(
 639                    f'Intent {intent} cannot be handled by AppMode type'
 640                    f' {modetype} (selector {self.mode_selector}'
 641                    f' incorrectly thinks that it can be).'
 642                )
 643
 644            # Ok; seems legit. Now instantiate the mode if necessary and
 645            # kick back to the logic thread to apply.
 646            mode = modetype()
 647            _babase.pushcall(
 648                tpartial(self._apply_intent, intent, mode),
 649                from_other_thread=True,
 650            )
 651        except Exception:
 652            logging.exception('Error setting app intent to %s.', intent)
 653            _babase.pushcall(
 654                tpartial(self._display_set_intent_error, intent),
 655                from_other_thread=True,
 656            )
 657
 658    def _apply_intent(self, intent: AppIntent, mode: AppMode) -> None:
 659        assert _babase.in_logic_thread()
 660
 661        # ONLY apply this intent if it is still the most recent one
 662        # submitted.
 663        if intent is not self._pending_intent:
 664            return
 665
 666        # If the app-mode for this intent is different than the active
 667        # one, switch.
 668        if type(mode) is not type(self._mode):
 669            if self._mode is None:
 670                is_initial_mode = True
 671            else:
 672                is_initial_mode = False
 673                try:
 674                    self._mode.on_deactivate()
 675                except Exception:
 676                    logging.exception(
 677                        'Error deactivating app-mode %s.', self._mode
 678                    )
 679            self._mode = mode
 680            try:
 681                mode.on_activate()
 682            except Exception:
 683                # Hmm; what should we do in this case?...
 684                logging.exception('Error activating app-mode %s.', mode)
 685
 686            # Let the world know when we first have an app-mode; certain
 687            # app stuff such as input processing can proceed at that
 688            # point.
 689            if is_initial_mode:
 690                _babase.on_initial_app_mode_set()
 691
 692        try:
 693            mode.handle_intent(intent)
 694        except Exception:
 695            logging.exception(
 696                'Error handling intent %s in app-mode %s.', intent, mode
 697            )
 698
 699    def _display_set_intent_error(self, intent: AppIntent) -> None:
 700        """Show the *user* something went wrong setting an intent."""
 701        from babase._language import Lstr
 702
 703        del intent
 704        _babase.screenmessage(Lstr(resource='errorText'), color=(1, 0, 0))
 705        _babase.getsimplesound('error').play()
 706
 707    def _on_initing(self) -> None:
 708        """Called when the app enters the initing state.
 709
 710        Here we can put together subsystems and other pieces for the
 711        app, but most things should not be doing any work yet.
 712        """
 713        # pylint: disable=cyclic-import
 714        from babase import _asyncio
 715        from babase import _appconfig
 716        from babase._apputils import AppHealthMonitor
 717        from babase import _env
 718
 719        assert _babase.in_logic_thread()
 720
 721        _env.on_app_state_initing()
 722
 723        self._asyncio_loop = _asyncio.setup_asyncio()
 724        self.health_monitor = AppHealthMonitor()
 725
 726        # __FEATURESET_APP_SUBSYSTEM_CREATE_BEGIN__
 727        # This section generated by batools.appmodule; do not edit.
 728
 729        # Poke these attrs to create all our subsystems.
 730        _ = self.plus
 731        _ = self.classic
 732        _ = self.ui_v1
 733
 734        # __FEATURESET_APP_SUBSYSTEM_CREATE_END__
 735
 736        # We're a pretty short-lived state. This should flip us to
 737        # 'loading'.
 738        self._init_completed = True
 739        self._update_state()
 740
 741    def _on_loading(self) -> None:
 742        """Called when we enter the loading state.
 743
 744        At this point, all built-in pieces of the app should be in place
 745        and can start talking to each other and doing work. Though at a
 746        high level, the goal of the app at this point is only to sign in
 747        to initial accounts, download workspaces, and otherwise prepare
 748        itself to really 'run'.
 749        """
 750        assert _babase.in_logic_thread()
 751
 752        # Get meta-system scanning built-in stuff in the bg.
 753        self.meta.start_scan(scan_complete_cb=self._on_meta_scan_complete)
 754
 755        # Inform all app subsystems in the same order they were inited.
 756        # Operate on a copy here because subsystems can still be added
 757        # at this point.
 758        for subsystem in self._subsystems.copy():
 759            try:
 760                subsystem.on_app_loading()
 761            except Exception:
 762                logging.exception(
 763                    'Error in on_app_loading for subsystem %s.', subsystem
 764                )
 765
 766        # Normally plus tells us when initial sign-in is done. If plus
 767        # is not present, however, we just do it ourself so we can
 768        # proceed on to the running state.
 769        if self.plus is None:
 770            _babase.pushcall(self.on_initial_sign_in_complete)
 771
 772    def _on_meta_scan_complete(self) -> None:
 773        """Called when meta-scan is done doing its thing."""
 774        assert _babase.in_logic_thread()
 775
 776        # Now that we know what's out there, build our final plugin set.
 777        self.plugins.on_meta_scan_complete()
 778
 779        assert not self._meta_scan_completed
 780        self._meta_scan_completed = True
 781        self._update_state()
 782
 783    def _on_running(self) -> None:
 784        """Called when we enter the running state.
 785
 786        At this point, all workspaces, initial accounts, etc. are in place
 787        and we can actually get started doing whatever we're gonna do.
 788        """
 789        assert _babase.in_logic_thread()
 790
 791        # Let our native layer know.
 792        _babase.on_app_running()
 793
 794        # Set a default app-mode-selector if none has been set yet
 795        # by a plugin or whatnot.
 796        if self._mode_selector is None:
 797            self._mode_selector = self.DefaultAppModeSelector()
 798
 799        # Inform all app subsystems in the same order they were
 800        # registered. Operate on a copy here because subsystems can
 801        # still be added at this point.
 802        #
 803        # NOTE: Do we need to allow registering still at this point? If
 804        # something gets registered here, it won't have its
 805        # on_app_running callback called. Hmm; I suppose that's the only
 806        # way that plugins can register subsystems though.
 807        for subsystem in self._subsystems.copy():
 808            try:
 809                subsystem.on_app_running()
 810            except Exception:
 811                logging.exception(
 812                    'Error in on_app_running for subsystem %s.', subsystem
 813                )
 814
 815        # Cut off new subsystem additions at this point.
 816        self._subsystem_registration_ended = True
 817
 818        # If 'exec' code was provided to the app, always kick that off
 819        # here as an intent.
 820        exec_cmd = _babase.exec_arg()
 821        if exec_cmd is not None:
 822            self.set_intent(AppIntentExec(exec_cmd))
 823        elif self._pending_intent is None:
 824            # Otherwise tell the app to do its default thing *only* if a
 825            # plugin hasn't already told it to do something.
 826            self.set_intent(AppIntentDefault())
 827
 828    def _apply_app_config(self) -> None:
 829        assert _babase.in_logic_thread()
 830
 831        _babase.lifecyclelog('apply-app-config')
 832
 833        # If multiple apply calls have been made, only actually apply
 834        # once.
 835        if not self._pending_apply_app_config:
 836            return
 837
 838        _pending_apply_app_config = False
 839
 840        # Inform all app subsystems in the same order they were inited.
 841        # Operate on a copy here because subsystems may still be able to
 842        # be added at this point.
 843        for subsystem in self._subsystems.copy():
 844            try:
 845                subsystem.do_apply_app_config()
 846            except Exception:
 847                logging.exception(
 848                    'Error in do_apply_app_config for subsystem %s.', subsystem
 849                )
 850
 851        # Let the native layer do its thing.
 852        _babase.do_apply_app_config()
 853
 854    def _update_state(self) -> None:
 855        # pylint: disable=too-many-branches
 856        assert _babase.in_logic_thread()
 857
 858        # Shutdown-complete trumps absolutely all.
 859        if self._native_shutdown_complete_called:
 860            if self.state is not self.State.SHUTDOWN_COMPLETE:
 861                self.state = self.State.SHUTDOWN_COMPLETE
 862                _babase.lifecyclelog('app state shutdown complete')
 863                self._on_shutdown_complete()
 864
 865        # Shutdown trumps all. Though we can't start shutting down until
 866        # init is completed since we need our asyncio stuff to exist for
 867        # the shutdown process.
 868        elif self._native_shutdown_called and self._init_completed:
 869            # Entering shutdown state:
 870            if self.state is not self.State.SHUTTING_DOWN:
 871                self.state = self.State.SHUTTING_DOWN
 872                _babase.lifecyclelog('app state shutting down')
 873                self._on_shutting_down()
 874
 875        elif self._native_suspended:
 876            # Entering suspended state:
 877            if self.state is not self.State.SUSPENDED:
 878                self.state = self.State.SUSPENDED
 879                self._on_suspend()
 880        else:
 881            # Leaving suspended state:
 882            if self.state is self.State.SUSPENDED:
 883                self._on_unsuspend()
 884
 885            # Entering or returning to running state
 886            if self._initial_sign_in_completed and self._meta_scan_completed:
 887                if self.state != self.State.RUNNING:
 888                    self.state = self.State.RUNNING
 889                    _babase.lifecyclelog('app state running')
 890                    if not self._called_on_running:
 891                        self._called_on_running = True
 892                        self._on_running()
 893            # Entering or returning to loading state:
 894            elif self._init_completed:
 895                if self.state is not self.State.LOADING:
 896                    self.state = self.State.LOADING
 897                    _babase.lifecyclelog('app state loading')
 898                    if not self._called_on_loading:
 899                        self._called_on_loading = True
 900                        self._on_loading()
 901
 902            # Entering or returning to initing state:
 903            elif self._native_bootstrapping_completed:
 904                if self.state is not self.State.INITING:
 905                    self.state = self.State.INITING
 906                    _babase.lifecyclelog('app state initing')
 907                    if not self._called_on_initing:
 908                        self._called_on_initing = True
 909                        self._on_initing()
 910
 911            # Entering or returning to native bootstrapping:
 912            elif self._native_start_called:
 913                if self.state is not self.State.NATIVE_BOOTSTRAPPING:
 914                    self.state = self.State.NATIVE_BOOTSTRAPPING
 915                    _babase.lifecyclelog('app state native bootstrapping')
 916            else:
 917                # Only logical possibility left is NOT_STARTED, in which
 918                # case we should not be getting called.
 919                logging.warning(
 920                    'App._update_state called while in %s state;'
 921                    ' should not happen.',
 922                    self.state.value,
 923                    stack_info=True,
 924                )
 925
 926    async def _shutdown(self) -> None:
 927        import asyncio
 928
 929        _babase.lock_all_input()
 930        try:
 931            async with asyncio.TaskGroup() as task_group:
 932                for task_coro in self._shutdown_tasks:
 933                    # Note: Mypy currently complains if we don't take
 934                    # this return value, but we don't actually need to.
 935                    # https://github.com/python/mypy/issues/15036
 936                    _ = task_group.create_task(
 937                        self._run_shutdown_task(task_coro)
 938                    )
 939        except* Exception:
 940            logging.exception('Unexpected error(s) in shutdown.')
 941
 942        # Note: ideally we should run this directly here, but currently
 943        # it does some legacy stuff which blocks, so running it here
 944        # gives us asyncio task-took-too-long warnings. If we can
 945        # convert those to nice graceful async tasks we should revert
 946        # this to a direct call.
 947        _babase.pushcall(_babase.complete_shutdown)
 948
 949    async def _run_shutdown_task(
 950        self, coro: Coroutine[None, None, None]
 951    ) -> None:
 952        """Run a shutdown task; report errors and abort if taking too long."""
 953        import asyncio
 954
 955        task = asyncio.create_task(coro)
 956        try:
 957            await asyncio.wait_for(task, self.SHUTDOWN_TASK_TIMEOUT_SECONDS)
 958        except Exception:
 959            logging.exception('Error in shutdown task (%s).', coro)
 960
 961    def _on_suspend(self) -> None:
 962        """Called when the app goes to a suspended state."""
 963        assert _babase.in_logic_thread()
 964
 965        # Suspend all app subsystems in the opposite order they were inited.
 966        for subsystem in reversed(self._subsystems):
 967            try:
 968                subsystem.on_app_suspend()
 969            except Exception:
 970                logging.exception(
 971                    'Error in on_app_suspend for subsystem %s.', subsystem
 972                )
 973
 974    def _on_unsuspend(self) -> None:
 975        """Called when unsuspending."""
 976        assert _babase.in_logic_thread()
 977        self.fg_state += 1
 978
 979        # Unsuspend all app subsystems in the same order they were inited.
 980        for subsystem in self._subsystems:
 981            try:
 982                subsystem.on_app_unsuspend()
 983            except Exception:
 984                logging.exception(
 985                    'Error in on_app_unsuspend for subsystem %s.', subsystem
 986                )
 987
 988    def _on_shutting_down(self) -> None:
 989        """(internal)"""
 990        assert _babase.in_logic_thread()
 991
 992        # Inform app subsystems that we're shutting down in the opposite
 993        # order they were inited.
 994        for subsystem in reversed(self._subsystems):
 995            try:
 996                subsystem.on_app_shutdown()
 997            except Exception:
 998                logging.exception(
 999                    'Error in on_app_shutdown for subsystem %s.', subsystem
1000                )
1001
1002        # Now kick off any async shutdown task(s).
1003        assert self._asyncio_loop is not None
1004        self._shutdown_task = self._asyncio_loop.create_task(self._shutdown())
1005
1006    def _on_shutdown_complete(self) -> None:
1007        """(internal)"""
1008        assert _babase.in_logic_thread()
1009
1010        # Inform app subsystems that we're done shutting down in the opposite
1011        # order they were inited.
1012        for subsystem in reversed(self._subsystems):
1013            try:
1014                subsystem.on_app_shutdown_complete()
1015            except Exception:
1016                logging.exception(
1017                    'Error in on_app_shutdown_complete for subsystem %s.',
1018                    subsystem,
1019                )
1020
1021    async def _wait_for_shutdown_suppressions(self) -> None:
1022        import asyncio
1023
1024        # Spin and wait for anything blocking shutdown to complete.
1025        starttime = _babase.apptime()
1026        _babase.lifecyclelog('shutdown-suppress wait begin')
1027        while _babase.shutdown_suppress_count() > 0:
1028            await asyncio.sleep(0.001)
1029        _babase.lifecyclelog('shutdown-suppress wait end')
1030        duration = _babase.apptime() - starttime
1031        if duration > 1.0:
1032            logging.warning(
1033                'Shutdown-suppressions lasted longer than ideal '
1034                '(%.2f seconds).',
1035                duration,
1036            )
1037
1038    async def _fade_and_shutdown_graphics(self) -> None:
1039        import asyncio
1040
1041        # Kick off a short fade and give it time to complete.
1042        _babase.lifecyclelog('fade-and-shutdown-graphics begin')
1043        _babase.fade_screen(False, time=0.15)
1044        await asyncio.sleep(0.15)
1045
1046        # Now tell the graphics system to go down and wait until
1047        # it has done so.
1048        _babase.graphics_shutdown_begin()
1049        while not _babase.graphics_shutdown_is_complete():
1050            await asyncio.sleep(0.01)
1051        _babase.lifecyclelog('fade-and-shutdown-graphics end')
1052
1053    async def _fade_and_shutdown_audio(self) -> None:
1054        import asyncio
1055
1056        # Tell the audio system to go down and give it a bit of
1057        # time to do so gracefully.
1058        _babase.lifecyclelog('fade-and-shutdown-audio begin')
1059        _babase.audio_shutdown_begin()
1060        await asyncio.sleep(0.15)
1061        while not _babase.audio_shutdown_is_complete():
1062            await asyncio.sleep(0.01)
1063        _babase.lifecyclelog('fade-and-shutdown-audio end')
1064
1065    def _threadpool_no_wait_done(self, fut: Future) -> None:
1066        try:
1067            fut.result()
1068        except Exception:
1069            logging.exception(
1070                'Error in work submitted via threadpool_submit_no_wait()'
1071            )
1072
1073    def _thread_pool_thread_init(self) -> None:
1074        # Help keep things clear in profiling tools/etc.
1075        self._pool_thread_count += 1
1076        _babase.set_thread_name(f'ballistica worker-{self._pool_thread_count}')