CoroutineWorker

public abstract class CoroutineWorker extends ListenableWorker

Object
   ↳ ListenableWorker
     ↳ 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]; 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 fields

@NonNull CoroutineDispatcher

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

Public constructors

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

Public methods

abstract @NonNull ListenableWorker.Result

A suspending method to do your work.

@NonNull ForegroundInfo
final @NonNull ListenableFuture<@NonNull ForegroundInfo>

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

final void

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

final void

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

final void

Updates the progress for the CoroutineWorker.

final @NonNull ListenableFuture<@NonNull ListenableWorker.Result>

Override this method to start your actual background processing.

Inherited methods

From class ListenableWorker
final @NonNull Context
@RestrictTo(value = RestrictTo.Scope.LIBRARY_GROUP) @NonNull Executor
final @NonNull UUID
final @NonNull Data
final @RequiresApi(value = "28") @Nullable Network
final @IntRange(from = "0") int
final @NonNull Set<@NonNull String>
@RestrictTo(value = RestrictTo.Scope.LIBRARY_GROUP) @NonNull TaskExecutor
final @RequiresApi(value = "24") @NonNull List<@NonNull String>
final @RequiresApi(value = "24") @NonNull List<@NonNull Uri>
@RestrictTo(value = RestrictTo.Scope.LIBRARY_GROUP) @NonNull WorkerFactory
@RestrictTo(value = RestrictTo.Scope.LIBRARY_GROUP) boolean
final boolean
final @RestrictTo(value = RestrictTo.Scope.LIBRARY_GROUP) boolean
final @NonNull ListenableFuture<@NonNull Void>
@NonNull ListenableFuture<@NonNull Void>
@RestrictTo(value = RestrictTo.Scope.LIBRARY_GROUP) void
setRunInForeground(boolean runInForeground)
final @RestrictTo(value = RestrictTo.Scope.LIBRARY_GROUP) void
final @RestrictTo(value = RestrictTo.Scope.LIBRARY_GROUP) void

Public fields

coroutineContext

@NonNull
public @NonNull CoroutineDispatcher coroutineContext

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

Public constructors

CoroutineWorker

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

Public methods

doWork

@NonNull
public abstract 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
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

@NonNull
public ForegroundInfo getForegroundInfo()
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

@NonNull
public final ListenableFuture<@NonNull ForegroundInfogetForegroundInfoAsync()

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<@NonNull ForegroundInfo>

A ListenableFuture of ForegroundInfo instance if the WorkRequest is marked immediate. For more information look at setExpedited.

onStopped

@NonNull
public final void onStopped()

This method is invoked when this Worker has been told to stop. At this point, the 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

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

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

@NonNull
public final ListenableFuture<@NonNull ListenableWorker.ResultstartWork()

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 ListenableFuture will be cancelled.

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

Returns
ListenableFuture<@NonNull ListenableWorker.Result>

A ListenableFuture with the Result of the computation. If you cancel this Future, WorkManager will treat this unit of work as failed.