Skip to content

topl-service / io.matthewnelson.topl_service.lifecycle / BackgroundManager


class BackgroundManager :ServiceConsts, LifecycleObserver (source)

When your application is sent to the background (the Recent App’s tray or lock screen), the chosen BackgroundManager.Builder.Policy will be triggered.

Additionally, there are 2 values for you to query if needed to give you context surrounding your application’s background state; taskIsInForeground and taskIsRemovedFromRecentApps.

If brought back into the foreground by the user:

While your application is in the foreground the only way to stop the service is by calling io.matthewnelson.topl_service.TorServiceController.stopTor, or via the io.matthewnelson.topl_service.notification.ServiceNotification Action (if enabled); The OS will not kill a service started using Context.startService & Context.bindService (how TorService is started) while in the foreground.

When the user sends your application to the Recent App’s tray though, to recoup resources the OS will kill your app after being idle for a period of time (random AF… typically 0.75m to 1.25m if the device’s memory is being used heavily) if the service is not moved to the Foreground to inhibit this. This is not an issue if the user removes the task before the OS kills the app, as Tor will be able to shutdown properly and the service will stop.

This is where Services get sketchy (especially when trying to implement an always running service for networking), and is the purpose of the BackgroundManager class.

This class starts your chosen BackgroundManager.Builder.Policy as soon as your application is sent to the background. It facilitates a more declarative, flexible operation to fit Library users’ needs.

See the BackgroundManager.Builder for more detail.


policy - The chosen BackgroundPolicy to be executed.

executionDelay - Length of time before the policy gets executed after the application is sent to the background.

serviceClass - The Service class being managed

bindServiceFlag - The flag to be used when binding to the service

See Also




Name Summary
Builder This BackgroundManager.Builder sets how you want the service to operate while your app is in the background (the Recent App’s tray or lock screen), such that things run reliably based off of your application’s needs.class Builder

Companion Object Properties

Name Summary
taskIsInForeground var taskIsInForeground:Boolean
taskIsRemovedFromRecentApps var taskIsRemovedFromRecentApps:Boolean