backgrounder/com.happycodelucky.backgrounder

Package-level declarations

Types

@ObjCName(swiftName = "AttemptFailureReason")

Why a MonitorEvent.AttemptFailed was emitted.

Optional lifecycle hook for app-level metrics — the imperative, callback-shaped delivery channel for the four v1 events (onScheduled / onStarted / onCompleted / onCancelled).

BackgrounderInitializer

class BackgrounderInitializer : Initializer<BackgroundTaskManager>

androidx.startup initializer that populates BackgroundTaskManager.shared before Application.onCreate runs. Registered in the library's manifest, so a consumer that keeps the InitializationProvider gets it for free.

BackgroundTaskManager

class BackgroundTaskManager

Constructed-instance entry point — held by the user's app graph for the app's lifetime.

BackgroundWorker

fun interface BackgroundWorker

A unit of background work the user implements.

BackgroundWorkerFactory

interface BackgroundWorkerFactory

A user-supplied factory that builds BackgroundWorkers for a set of task ids, resolving the concrete worker lazily at dispatch time.

BackoffPolicy

@Serializable

sealed interface BackoffPolicy

How a WorkRequest is retried after WorkResult.Retry.

BGTaskSchedulerPermittedIdentifier

@Target(allowedTargets = [AnnotationTarget.FIELD])

annotation class BGTaskSchedulerPermittedIdentifier

Marks a const val String as an identifier that must appear in the iOS app's BGTaskSchedulerPermittedIdentifiers Info.plist array.

CancelOutcome

sealed interface CancelOutcome

The result of Scheduler.cancel / Scheduler.cancelAll.

CancelSource

@ObjCName(swiftName = "CancelSource")

sealed interface CancelSource

Why a MonitorEvent.Cancelled was emitted.

ConflictPolicy

enum ConflictPolicy : Enum<ConflictPolicy>

What Scheduler.schedule does when a request with the same task id is already pending.

DeferralReason

@ObjCName(swiftName = "DeferralReason")

sealed interface DeferralReason

Why a MonitorEvent.AttemptDeferred was emitted.

ExecutionHint

@Serializable

sealed interface ExecutionHint

A scheduling hint about how the platform should treat a WorkRequest.

FactoryDescriptor

@ObjCName(swiftName = "FactoryDescriptor")

sealed interface FactoryDescriptor

Inspector-shaped view of one registered factory.

MonitorEvent

@ObjCName(swiftName = "MonitorEvent")

sealed interface MonitorEvent

Sealed event stream emitted by the library for instrumentation / inspection.

NetworkRequirement

enum NetworkRequirement : Enum<NetworkRequirement>

Network connectivity requirement for a WorkRequest.

PendingPredicate

@ObjCName(swiftName = "PendingPredicate")

sealed interface PendingPredicate

A single condition currently preventing a scheduled task from running.

PlatformCapabilities

data class PlatformCapabilities(val maxExecutionTime: Duration, val cancelsInFlight: Boolean)

What the platform-currently-running-this-worker can do.

PlatformDiagnostic

@ObjCName(swiftName = "PlatformDiagnostic")

sealed interface PlatformDiagnostic

A configuration or environment issue the library has detected that could stop scheduled work from running.

PlatformDiagnostics

@ObjCName(swiftName = "PlatformDiagnostics")

data class PlatformDiagnostics(val diagnostics: List<PlatformDiagnostic>)

Result of BackgroundTaskManager.diagnostics — list of currently-active PlatformDiagnostics. An empty list means the library believes the environment is configured correctly.

QuotaPolicy

enum QuotaPolicy : Enum<QuotaPolicy>

What Android does when expedited quota is exhausted. Maps to androidx.work.OutOfQuotaPolicy. iOS ignores it (no quota concept).

ScheduledTask

data class ScheduledTask(val taskId: String, val kind: ScheduledTask.Kind, val state: ScheduledTask.State, val nextRunHint: Instant?, val attempt: Int, val ephemeral: Boolean, val pendingPredicates: List<PendingPredicate> = emptyList())

A snapshot of one scheduled task's current state — returned from Scheduler.scheduled for inspection.

ScheduleOutcome

sealed interface ScheduleOutcome

The result of Scheduler.schedule.

SchedulerGuarantees

data class SchedulerGuarantees(val survivesProcessDeath: Boolean, val survivesReboot: Boolean, val survivesForceQuit: Boolean, val honoursWallClock: Boolean, val supportsRetryBackoff: Boolean, val cancelsInFlight: Boolean, val minimumPeriodicInterval: Duration?, val maxConcurrentTasks: Int?)

What the current platform's Scheduler actually guarantees.

SkipReason

@ObjCName(swiftName = "SkipReason")

sealed interface SkipReason

Why a MonitorEvent.Skipped was emitted — structurally unrecoverable.

WorkConstraints

@Serializable

data class WorkConstraints(val networkRequired: NetworkRequirement = NetworkRequirement.None, val requiresCharging: Boolean = false, val requiresDeviceIdle: Boolean = false)

Conditions a WorkRequest needs satisfied before the platform scheduler will dispatch it.

WorkerContext

class WorkerContext

Per-invocation state handed to a BackgroundWorker's execute() call.

WorkerRegistry

class WorkerRegistry

The DI seam: resolves a stable task id to a fresh BackgroundWorker per invocation. Two registration shapes feed it:

WorkInput

@Serializable

class WorkInput

A typed key/value bag passed to a BackgroundWorker at scheduling time.

WorkRequest

@Serializable

sealed interface WorkRequest

A request to schedule background work, identified by a stable task id.

WorkResult

sealed interface WorkResult

The outcome a BackgroundWorker returns from execute().

WorkValue

@Serializable

sealed interface WorkValue

A value carried in a WorkInput payload.

Properties

shared

@HiddenFromObjC

val BackgroundTaskManager.Companion.shared: BackgroundTaskManager

The process-wide BackgroundTaskManager.

Functions

androidWorkerFactory

fun BackgroundTaskManager.androidWorkerFactory(): WorkerFactory

The WorkerFactory to install in your WorkManager.Configuration. Compose with DelegatingWorkerFactory if you also use Hilt's HiltWorkerFactory or any other custom factory.

configure

fun BackgroundTaskManager.Companion.configure(application: Application, eventListener: BackgrounderEventListener = BackgrounderEventListener.Noop, workManager: WorkManager? = null): BackgroundTaskManager

Android entry point: builds the process-wide BackgroundTaskManager and installs it as BackgroundTaskManager.shared.

create

@ObjCName(swiftName = "create")

fun BackgroundTaskManager.Companion.create(tickIdentifier: String, eventListener: BackgrounderEventListener = BackgrounderEventListener.Noop): BackgroundTaskManager

iOS factory for BackgroundTaskManager. Installs the result as BackgroundTaskManager.shared.

fun BackgroundTaskManager.Companion.create(eventListener: BackgrounderEventListener = BackgrounderEventListener.Noop): BackgroundTaskManager

JVM (desktop / server) factory for BackgroundTaskManager.

@ObjCName(swiftName = "create")

fun BackgroundTaskManager.Companion.create(eventListener: BackgrounderEventListener = BackgrounderEventListener.Noop): BackgroundTaskManager

macOS factory for BackgroundTaskManager.

defaultTickIdentifier

@ObjCName(swiftName = "defaultTickIdentifier")

fun BackgroundTaskManager.Companion.defaultTickIdentifier(): String

The tick identifier BackgroundTaskManager.shared uses when the app never called create: the main bundle identifier plus .backgrounder-tick (e.g. dev.example.app.backgrounder-tick). It must appear in BGTaskSchedulerPermittedIdentifiers; the Gradle plugin adds it when backgrounder.iosBundleIdentifier is set. Exposed so apps that maintain the plist by hand can read the exact string.

sharedInstance

@ObjCName(swiftName = "sharedInstance")

fun BackgroundTaskManager.Companion.sharedInstance(): BackgroundTaskManager

Objective-C-visible accessor for shared. Swift callers use BackgroundTaskManager.shared, a bundled wrapper over this function; Kotlin callers use the shared property. Exists only because the property name collides with Kotlin/Native's generated companion accessor.