CoroutineWorker

Added in 1.0.0

Kotlin |Java

public abstract class CoroutineWorker extends ListenableWorker

java.lang.Object
↳	androidx.work.ListenableWorker
	↳	androidx.work.CoroutineWorker

A ListenableWorker implementation that provides interop with Kotlin Coroutines. Override the doWork function to do your suspending work.

By default, CoroutineWorker runs on Dispatchers.Default if neither Configuration.Builder.setExecutor or Configuration.Builder.setWorkerCoroutineContext were set.

A CoroutineWorker is given a maximum of ten minutes to finish its execution and return a [ListenableWorker.Result]. After this time has expired, the worker will be signalled to stop.

Summary

Public constructors
`CoroutineWorker( @NonNull Context appContext, @NonNull WorkerParameters params )`

Public methods
`abstract @NonNull ListenableWorker.Result`	`doWork()` A suspending method to do your work.
`@NonNull CoroutineDispatcher`	`getCoroutineContext()` The coroutine context on which `doWork` will run.
`@NonNull ForegroundInfo`	`getForegroundInfo()`
`final @NonNull ListenableFuture<@NonNull ForegroundInfo>`	`getForegroundInfoAsync()` Return an instance of `ForegroundInfo` if the `WorkRequest` is important to the user.
`final void`	`onStopped()` This method is invoked when this Worker has been told to stop.
`final void`	`setForeground(@NonNull ForegroundInfo foregroundInfo)` Makes the `CoroutineWorker` run in the context of a foreground `android.app.Service`.
`final void`	`setProgress(@NonNull Data data)` Updates the progress for the `CoroutineWorker`.
`final @NonNull ListenableFuture<@NonNull ListenableWorker.Result>`	`startWork()` Override this method to start your actual background processing.

Inherited methods

From androidx.work.ListenableWorker

`final @NonNull Context`	`getApplicationContext()` Gets the application `android.content.Context`.
`final @NonNull UUID`	`getId()` Gets the ID of the `WorkRequest` that created this Worker.
`final @NonNull Data`	`getInputData()` Gets the input data.
`final @Nullable Network`	`@RequiresApi(value = 28) getNetwork()` Gets the `android.net.Network` to use for this Worker.
`final @IntRange(from = 0) int`	`getRunAttemptCount()` Gets the current run attempt count for this work.
`final int`	`@RequiresApi(value = 31) getStopReason()` Returns a reason why this worker has been stopped.
`final @NonNull Set<@NonNull String>`	`getTags()` Gets a `java.util.Set` of tags associated with this Worker's `WorkRequest`.
`final @NonNull List<@NonNull String>`	`@RequiresApi(value = 24) getTriggeredContentAuthorities()` Gets the list of content authorities that caused this Worker to execute.
`final @NonNull List<@NonNull Uri>`	`@RequiresApi(value = 24) getTriggeredContentUris()` Gets the list of content `android.net.Uri`s that caused this Worker to execute.
`final boolean`	`isStopped()` Returns `true` if this Worker has been told to stop.
`final @NonNull ListenableFuture<@NonNull Void>`	`setForegroundAsync(@NonNull ForegroundInfo foregroundInfo)` This specifies that the `WorkRequest` is long-running or otherwise important.
`@NonNull ListenableFuture<@NonNull Void>`	`setProgressAsync(@NonNull Data data)` Updates `ListenableWorker` progress.

Public constructors

CoroutineWorker

Added in 1.0.0

public CoroutineWorker(
    @NonNull Context appContext,
    @NonNull WorkerParameters params
)

Public methods

doWork

public abstract @NonNull ListenableWorker.Result doWork()

A suspending method to do your work.

To specify which [CoroutineDispatcher] your work should run on, use `withContext()` within `doWork()`. If there is no other dispatcher declared, [Dispatchers.Default] will be used.

A CoroutineWorker is given a maximum of ten minutes to finish its execution and return a [ListenableWorker.Result]. After this time has expired, the worker will be signalled to stop.

Returns
`@NonNull ListenableWorker.Result`	The `ListenableWorker.Result` of the result of the background work; note that dependent work will not execute if you return `ListenableWorker.Result.failure`

getCoroutineContext

Added in 1.0.0

Deprecated in 2.1.0

public @NonNull CoroutineDispatcher getCoroutineContext()

The coroutine context on which doWork will run.

If this property is overridden then it takes precedent over Configuration.executor or Configuration.workerCoroutineContext.

By default, this is a dispatcher delegating to Dispatchers.Default

getForegroundInfo

public @NonNull ForegroundInfo getForegroundInfo()

Returns
`@NonNull ForegroundInfo`	The `ForegroundInfo` instance if the `WorkRequest` is marked as expedited.

Throws
`kotlin.IllegalStateException`	when not overridden. Override this method when the corresponding `WorkRequest` is marked expedited.

getForegroundInfoAsync

Added in 2.7.0

public final @NonNull ListenableFuture<@NonNull ForegroundInfo> getForegroundInfoAsync()

Return an instance of ForegroundInfo if the WorkRequest is important to the user. In this case, WorkManager provides a signal to the OS that the process should be kept alive while this work is executing.

Prior to Android S, WorkManager manages and runs a foreground service on your behalf to execute the WorkRequest, showing the notification provided in the ForegroundInfo. To update this notification subsequently, the application can use android.app.NotificationManager.

Starting in Android S and above, WorkManager manages this WorkRequest using an immediate job.

Returns
`@NonNull ListenableFuture<@NonNull ForegroundInfo>`	A `com.google.common.util.concurrent.ListenableFuture` of `ForegroundInfo` instance if the WorkRequest is marked immediate. For more information look at `setExpedited`.

onStopped

Added in 1.0.0

public final void onStopped()

This method is invoked when this Worker has been told to stop. At this point, the com.google.common.util.concurrent.ListenableFuture returned by the instance of startWork is also cancelled. This could happen due to an explicit cancellation signal by the user, or because the system has decided to preempt the task. In these cases, the results of the work will be ignored by WorkManager. All processing in this method should be lightweight - there are no contractual guarantees about which thread will invoke this call, so this should not be a long-running or blocking operation.

setForeground

Added in 2.3.0

public final void setForeground(@NonNull ForegroundInfo foregroundInfo)

Makes the CoroutineWorker run in the context of a foreground android.app.Service. This is a suspending function unlike the setForegroundAsync API which returns a ListenableFuture.

Calling setForeground will throw an IllegalStateException if the process is subject to foreground service restrictions. Consider using WorkRequest.Builder.setExpedited and getForegroundInfo instead.

Parameters
`@NonNull ForegroundInfo foregroundInfo`	The `ForegroundInfo`

setProgress

Added in 2.3.0

public final void setProgress(@NonNull Data data)

Updates the progress for the CoroutineWorker. This is a suspending function unlike the setProgressAsync API which returns a ListenableFuture.

Parameters
`@NonNull Data data`	The progress `Data`

startWork

Added in 1.0.0

public final @NonNull ListenableFuture<@NonNull ListenableWorker.Result> startWork()

Override this method to start your actual background processing. This method is called on the main thread.

A ListenableWorker has a well defined execution window to to finish its execution and return a Result. After this time has expired, the worker will be signalled to stop and its com.google.common.util.concurrent.ListenableFuture will be cancelled.

The future will also be cancelled if this worker is stopped for any reason (see onStopped).

Returns
`@NonNull ListenableFuture<@NonNull ListenableWorker.Result>`	A `com.google.common.util.concurrent.ListenableFuture` with the `Result` of the computation. If you cancel this Future, WorkManager will treat this unit of work as failed.