<!--
{
  "availability" : [
    "macOS: 10.10.0 -"
  ],
  "documentType" : "symbol",
  "framework" : "Foundation",
  "identifier" : "/documentation/Foundation/NSBackgroundActivityScheduler",
  "metadataVersion" : "0.1.0",
  "role" : "Class",
  "symbol" : {
    "kind" : "Class",
    "modules" : [
      "Foundation"
    ],
    "preciseIdentifier" : "c:objc(cs)NSBackgroundActivityScheduler"
  },
  "title" : "NSBackgroundActivityScheduler"
}
-->

# NSBackgroundActivityScheduler

A task scheduler suitable for low priority operations that can run in the background.

```
class NSBackgroundActivityScheduler
```

## Overview

Use an [`NSBackgroundActivityScheduler`](/documentation/Foundation/NSBackgroundActivityScheduler) object to schedule an arbitrary maintenance or background task. It’s similar to an [`Timer`](/documentation/Foundation/Timer) object, in that it lets you schedule a repeating or non-repeating task. However, [`NSBackgroundActivityScheduler`](/documentation/Foundation/NSBackgroundActivityScheduler) gives the system flexibility to determine the most efficient time to execute based on energy usage, thermal conditions, and CPU use.

For example, use an [`NSBackgroundActivityScheduler`](/documentation/Foundation/NSBackgroundActivityScheduler) object to schedule:

- Automatic saves
- Backups
- Data maintenance
- Periodic content fetches
- Installation of updates
- Activities occurring in intervals of 10 minutes or more
- Any other deferrable task

For information about performing non-deferrable tasks efficiently, see [Specify Nondeferrable Background Activities](https://developer.apple.com/library/archive/documentation/Performance/Conceptual/power_efficiency_guidelines_osx/SchedulingBackgroundActivity.html#//apple_ref/doc/uid/TP40013929-CH32-SW10) in [Energy Efficiency Guide for Mac Apps](https://developer.apple.com/library/archive/documentation/Performance/Conceptual/power_efficiency_guidelines_osx/index.html#//apple_ref/doc/uid/TP40013929).

> Note:
> The ``doc://com.apple.foundation/documentation/Foundation/NSBackgroundActivityScheduler`` class interfaces with the XPC Activity API. However, your app doesn’t need to be an XPC service in order to use ``doc://com.apple.foundation/documentation/Foundation/NSBackgroundActivityScheduler``.

### Create a Scheduler

To initialize a scheduler, call [`init(identifier:)`](/documentation/Foundation/NSBackgroundActivityScheduler/init(identifier:)) for `NSBackgroundActivityScheduler`, and pass it a unique identifier string in reverse DNS notation (`nil` and zero-length strings are not allowed) that remains constant across launches of your application.

```swift
let activity = NSBackgroundActivityScheduler(identifier: "com.example.MyApp.updatecheck")
```

> Note:
> The system uses this unique identifier to track the number of times the activity has run and to improve the heuristics for deciding when to run it again in the future.

### Configure Scheduler Properties

Configure the scheduler with any of the following scheduling properties:

- [`repeats`](/documentation/Foundation/NSBackgroundActivityScheduler/repeats)—If set to <doc://com.apple.documentation/documentation/Swift/true>, the activity is rescheduled at the specified interval after finishing.
- [`interval`](/documentation/Foundation/NSBackgroundActivityScheduler/interval)—For repeating schedulers, the average interval between invocations of the activity. For nonrepeating schedulers, `interval` is the suggested interval of time between scheduling the activity and the invocation of the activity.
- [`tolerance`](/documentation/Foundation/NSBackgroundActivityScheduler/tolerance)—The amount of time before or after the nominal fire date when the activity should be invoked. The nominal fire date is calculated by using the interval combined with the previous fire date or the time when the activity is started. These two properties create a window in time, during which the activity may be scheduled. The system will more aggressively schedule the activity as it nears the end of the grace period after the nominal fire date. The default value is half the interval.
- [`qualityOfService`](/documentation/Foundation/NSBackgroundActivityScheduler/qualityOfService)—The default value is `NSQualityOfServiceBackground`. If you upgrade the quality of service above this level, the system schedules the activity more aggressively. The default value is the recommended value for most activities. For information on quality of service, see [Prioritize Work at the Task Level](https://developer.apple.com/library/archive/documentation/Performance/Conceptual/power_efficiency_guidelines_osx/PrioritizeWorkAtTheTaskLevel.html#//apple_ref/doc/uid/TP40013929-CH35) in [Energy Efficiency Guide for Mac Apps](https://developer.apple.com/library/archive/documentation/Performance/Conceptual/power_efficiency_guidelines_osx/index.html#//apple_ref/doc/uid/TP40013929).

The next three code examples demonstrate different scheduling scenarios.

Scheduling an activity to fire in the next 10 minutes

```swift
activity.tolerance = 10 * 60
```

Scheduling an activity to fire between 15 and 45 minutes from now

```swift
activity.interval = 30 * 60
activity.tolerance = 15 * 60
```

Scheduling an activity to fire once each hour

```swift
activity.repeats = true
activity.interval = 60 * 60
```

### Schedule Activity with scheduleWithBlock:

When you’re ready to schedule the activity, call `scheduleWithBlock:` and provide a block of code to execute when the scheduler runs, as shown in the following example. The block will be called on a serial background queue appropriate for the level of quality of service specified. The system automatically uses the [`beginActivity(options:reason:)`](/documentation/Foundation/ProcessInfo/beginActivity(options:reason:)) method (of [`ProcessInfo`](/documentation/Foundation/ProcessInfo)) while invoking the block, choosing appropriate options based on the specified quality of service.

When your block is called, it’s passed a completion handler as an argument. Configure the block to invoke this handler, passing it a result of type [`NSBackgroundActivityScheduler.Result`](/documentation/Foundation/NSBackgroundActivityScheduler/Result) to indicate whether the activity finished ([`NSBackgroundActivityScheduler.Result.finished`](/documentation/Foundation/NSBackgroundActivityScheduler/Result/finished)) or should be deferred ([`NSBackgroundActivityScheduler.Result.deferred`](/documentation/Foundation/NSBackgroundActivityScheduler/Result/deferred)) and rescheduled for a later time. Failure to invoke the completion handler results in the activity not being rescheduled. For work that will be deferred and rescheduled, the block may optionally adjust scheduler properties, such as [`interval`](/documentation/Foundation/NSBackgroundActivityScheduler/interval) or [`tolerance`](/documentation/Foundation/NSBackgroundActivityScheduler/tolerance), before calling the completion handler.

Scheduling background activity

```swift
activity.scheduleWithBlock() { (completion: NSBackgroundActivityCompletionHandler) in
    // Perform the activity
    self.completion(NSBackgroundActivityResult.Finished)
}
```

### Detect Whether to Defer Activity

It’s conceivable that while a lengthy activity is running, conditions may change, resulting in the activity now requiring deferral. For example, perhaps the user has unplugged the Mac and it’s now running on battery power. Your activity can call [`shouldDefer`](/documentation/Foundation/NSBackgroundActivityScheduler/shouldDefer) to determine whether this has occurred. A value of <doc://com.apple.documentation/documentation/Swift/true> indicates that the block should finish what it’s currently doing and invoke its completion handler with a value of [`NSBackgroundActivityScheduler.Result.deferred`](/documentation/Foundation/NSBackgroundActivityScheduler/Result/deferred). See the following example.

Detecting deferred background activity

```swift
if activity.shouldDefer {
    // Wrap up processing and prepare to defer activity
    self.completion(NSBackgroundActivityResult.Deferred)
} else {
    // Continue processing
    self.completion(NSBackgroundActivityResult.Finished)
}
```

### Stop Activity

Call [`invalidate()`](/documentation/Foundation/NSBackgroundActivityScheduler/invalidate()) to stop scheduling an activity, as shown in the following example.

Stopping background activity

```swift
activity.invalidate()
```

> Note:
> When an activity is stopped, a block that’s currently executing will still finish executing.

## Topics

### Background Scheduler Attributes

[`identifier`](/documentation/Foundation/NSBackgroundActivityScheduler/identifier)

A unique reverse DNS notation string, such as `com.example.MyApp.updatecheck`, that identifies the activity.

[`repeats`](/documentation/Foundation/NSBackgroundActivityScheduler/repeats)

A Boolean value indicating whether the activity should be rescheduled after it completes.

[`interval`](/documentation/Foundation/NSBackgroundActivityScheduler/interval)

An integer providing a suggested interval between scheduling and invoking the activity.

[`qualityOfService`](/documentation/Foundation/NSBackgroundActivityScheduler/qualityOfService)

A value of type `NSQualityOfService`, which controls how aggressively the system schedules the activity.

[`shouldDefer`](/documentation/Foundation/NSBackgroundActivityScheduler/shouldDefer)

A Boolean value indicating whether your app should stop performing background activity and resume at a more optimal time.

[`tolerance`](/documentation/Foundation/NSBackgroundActivityScheduler/tolerance)

A value of type [`TimeInterval`](/documentation/Foundation/TimeInterval), which specifies a range of time during which the background activity may occur.

### Initializing Schedulers

[`init(identifier:)`](/documentation/Foundation/NSBackgroundActivityScheduler/init(identifier:))

Initializes a background activity scheduler object with a specified unique identifier.

### Scheduling Activity

[`schedule(_:)`](/documentation/Foundation/NSBackgroundActivityScheduler/schedule(_:))

Begins scheduling the background activity.

[`NSBackgroundActivityScheduler.CompletionHandler`](/documentation/Foundation/NSBackgroundActivityScheduler/CompletionHandler)

### Stopping Scheduled Activity

[`invalidate()`](/documentation/Foundation/NSBackgroundActivityScheduler/invalidate())

Prevents the background activity from being scheduled again.

### Constants

[`NSBackgroundActivityScheduler.Result`](/documentation/Foundation/NSBackgroundActivityScheduler/Result)

These constants indicate whether background activity has been completed successfully or whether additional processing should be deferred until a more optimal time.

[`QualityOfService`](/documentation/Foundation/QualityOfService)

Constants that indicate the nature and importance of work to the system.


---

Copyright &copy; 2026 Apple Inc. All rights reserved. | [Terms of Use](https://www.apple.com/legal/internet-services/terms/site.html) | [Privacy Policy](https://www.apple.com/privacy/privacy-policy)