CoroutineWorker

abstract class CoroutineWorker : ListenableWorker


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]; this can be modified by overriding [coroutineContext].

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(appContext: Context, params: WorkerParameters)

Public functions

abstract suspend ListenableWorker.Result

A suspending method to do your work.

open suspend ForegroundInfo
final ListenableFuture<ForegroundInfo>

Return an instance of ForegroundInfo if the WorkRequest is important to the user.

final Unit

This method is invoked when this Worker has been told to stop.

suspend Unit
setForeground(foregroundInfo: ForegroundInfo)

Makes the CoroutineWorker run in the context of a foreground android.app.Service.

suspend Unit

Updates the progress for the CoroutineWorker.

final ListenableFuture<ListenableWorker.Result>

Override this method to start your actual background processing.

Public properties

open CoroutineDispatcher

This property is deprecated. use withContext(...) inside doWork() instead.

Inherited functions

From androidx.work.ListenableWorker
Context

Gets the application android.content.Context.

UUID

Gets the ID of the WorkRequest that created this Worker.

Data

Gets the input data.

Network?
@RequiresApi(value = 28)
getNetwork()

Gets the android.net.Network to use for this Worker.

@IntRange(from = 0) Int

Gets the current run attempt count for this work.

Int

Returns a reason why this worker has been stopped.

MutableSet<String>

Gets a java.util.Set of tags associated with this Worker's WorkRequest.

MutableList<String>

Gets the list of content authorities that caused this Worker to execute.

MutableList<Uri>

Gets the list of content android.net.Uris that caused this Worker to execute.

Boolean

Returns true if this Worker has been told to stop.

ListenableFuture<Void>

This specifies that the WorkRequest is long-running or otherwise important.

open ListenableFuture<Void>

Updates ListenableWorker progress.

Public constructors

CoroutineWorker

Added in 1.0.0
CoroutineWorker(appContext: Context, params: WorkerParameters)

Public functions

doWork

abstract suspend fun doWork(): ListenableWorker.Result

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
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

getForegroundInfo

open suspend fun getForegroundInfo(): ForegroundInfo
Returns
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
final fun getForegroundInfoAsync(): ListenableFuture<ForegroundInfo>

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
ListenableFuture<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
final fun onStopped(): Unit

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
suspend fun setForeground(foregroundInfo: ForegroundInfo): Unit

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
foregroundInfo: ForegroundInfo

The ForegroundInfo

setProgress

Added in 2.3.0
suspend fun setProgress(data: Data): Unit

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

Parameters
data: Data

The progress Data

startWork

Added in 1.0.0
final fun startWork(): ListenableFuture<ListenableWorker.Result>

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
ListenableFuture<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.

Public properties

coroutineContext

Added in 1.0.0
Deprecated in 2.1.0
open val coroutineContextCoroutineDispatcher

The coroutine context on which doWork will run. By default, this is Dispatchers.Default.