babase

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

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

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