Instance Method

beginBackgroundTask(expirationHandler:)

Marks the beginning of a new long-running background task.

Declaration

func beginBackgroundTask(expirationHandler handler: (() -> Void)? = nil) -> UIBackgroundTaskIdentifier

Parameters

handler

A handler to be called shortly before the app’s remaining background time reaches 0. You should use this handler to clean up and mark the end of the background task. Failure to end the task explicitly will result in the termination of the app. The handler is called synchronously on the main thread, blocking the app’s suspension momentarily while the app is notified.

Return Value

A unique identifier for the new background task. You must pass this value to the endBackgroundTask(_:) method to mark the end of this task. This method returns UIBackgroundTaskInvalid if running in the background is not possible.

Discussion

This method lets your app continue to run for a period of time after it transitions to the background. You should call this method at times where leaving a task unfinished might be detrimental to your app’s user experience. For example, your app could call this method to ensure that had enough time to transfer an important file to a remote server or at least attempt to make the transfer and note any errors. You should not use this method simply to keep your app running after it moves to the background.

Each call to this method must be balanced by a matching call to the endBackgroundTask(_:) method. Apps running background tasks have a finite amount of time in which to run them. (You can find out how much time is available using the backgroundTimeRemaining property.) If you do not call endBackgroundTask(_:) for each task before time expires, the system kills the app. If you provide a block object in the handler parameter, the system calls your handler before time expires to give you a chance to end the task.

You can call this method at any point in your app’s execution. You may also call this method multiple times to mark the beginning of several background tasks that run in parallel. However, each task must be ended separately. You identify a given task using the value returned by this method.

To assist with debugging, this method generates a name for the task that is based on the name of the calling method or function. If you want to specify a custom name, use the beginBackgroundTask(withName:expirationHandler:) method instead.

This method can be safely called on a non-main thread. To extend the execution time of an app extension, use the performExpiringActivity(withReason:using:) method of ProcessInfo instead.

See Also

Managing Background Execution

var applicationState: UIApplicationState

The runtime state of the app.

var backgroundTimeRemaining: TimeInterval

The amount of time the app has to run in the background.

var backgroundRefreshStatus: UIBackgroundRefreshStatus

The ability of the app to be launched into the background so that it can perform background behaviors.

func setMinimumBackgroundFetchInterval(TimeInterval)

Specifies the minimum amount of time that must elapse between background fetch operations.

func beginBackgroundTask(withName: String?, expirationHandler: (() -> Void)? = nil)

Marks the beginning of a new long-running background task with the specified name.

func endBackgroundTask(UIBackgroundTaskIdentifier)

Marks the end of a specific long-running background task.