Stay organized with collections
Save and categorize content based on your preferences.
abstract class CancellationToken
Propagates notification that operations should be canceled.
Developers writing methods that return a Task should take a CancellationToken
as a parameter if they wish to make the Task cancelable (see below code snippet). A CancellationToken
can only be created by creating a new instance of . CancellationToken
is immutable and must be canceled by calling cancel
on the CancellationTokenSource
that creates it. It can only be canceled once. If canceled, it should not be passed to future operations.
When cancel
is called, all the Tasks with the CancellationToken
from that CancellationTokenSource
will be canceled. This operation only flags those Tasks as canceled, and the API author is responsible for stopping whatever the Task is actually doing to free up the resources.
Cancellable Task
example:
public
Task<Integer>
doSomething
(
CancellationToken
token
)
{
// Attach a listener that will be called once cancellation is requested.
token
.
onCanceledRequested
(
new
OnTokenCanceledListener
()
{
@Override
public
void
onCanceled
()
{
// Some other operations to cancel this Task, such as free resources...
}
});
final
TaskCompletionSource<Integer>
tcs
=
new
TaskCompletionSource
<> (
token
);
// do something...
}
CancellationTokenSource
cts
=
new
CancellationTokenSource
();
Task<Integer>
task
=
doSomething
(
cts
.
getToken
());
cts
.
cancel
();
Cancellable Task
example in android.app.Activity
context: public
class
MyActivity
extends
Activity
{
// ...
@Override
public
void
onStart
()
{
super
.
onStart
();
// Typically use one cancellation source per lifecycle.
cancellationSource
=
new
CancellationTokenSource
();
// That source's token can be passed to multiple calls.
doSomethingCancellable
(
cancellationSource
.
getToken
())
.
onSuccessTask
(
result
-
>
doSomethingElse
(
result
,
cancellationSource
.
getToken
()));
}
@Override
public
void
onStop
()
{
super
.
onStop
();
cancellationSource
.
cancel
();
}
}
Summary
Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 4.0 License
, and code samples are licensed under the Apache 2.0 License
. For details, see the Google Developers Site Policies
. Java is a registered trademark of Oracle and/or its affiliates.
Last updated 2024-10-31 UTC.
[[["Easy to understand","easyToUnderstand","thumb-up"],["Solved my problem","solvedMyProblem","thumb-up"],["Other","otherUp","thumb-up"]],[["Missing the information I need","missingTheInformationINeed","thumb-down"],["Too complicated / too many steps","tooComplicatedTooManySteps","thumb-down"],["Out of date","outOfDate","thumb-down"],["Samples / code issue","samplesCodeIssue","thumb-down"],["Other","otherDown","thumb-down"]],["Last updated 2024-10-31 UTC."],[[["\u003cp\u003e\u003ccode\u003eCancellationToken\u003c/code\u003e propagates cancellation notifications to cancelable tasks.\u003c/p\u003e\n"],["\u003cp\u003eDevelopers can create cancelable tasks by passing a \u003ccode\u003eCancellationToken\u003c/code\u003e to their methods.\u003c/p\u003e\n"],["\u003cp\u003e\u003ccode\u003eCancellationTokenSource\u003c/code\u003e is used to create and cancel \u003ccode\u003eCancellationToken\u003c/code\u003e instances.\u003c/p\u003e\n"],["\u003cp\u003eWhen a \u003ccode\u003eCancellationToken\u003c/code\u003e is canceled, associated tasks are flagged, requiring API authors to handle resource cleanup.\u003c/p\u003e\n"],["\u003cp\u003eIt's recommended to use one \u003ccode\u003eCancellationTokenSource\u003c/code\u003e per lifecycle, such as within an Activity.\u003c/p\u003e\n"]]],[],null,["# CancellationToken\n=================\n\nKotlin \\|[Java](/android/reference/com/google/android/gms/tasks/CancellationToken \"View this page in Java\") \n\n\n```\nabstract class CancellationToken\n```\n\n\u003cbr /\u003e\n\n*** ** * ** ***\n\nPropagates notification that operations should be canceled.\n\nDevelopers writing methods that return a Task should take a `CancellationToken` as a parameter if they wish to make the Task cancelable (see below code snippet). A `\nCancellationToken` can only be created by creating a new instance of . `CancellationToken` is immutable and must be canceled by calling [cancel](/android/reference/kotlin/com/google/android/gms/tasks/CancellationTokenSource#cancel()) on the [CancellationTokenSource](/android/reference/kotlin/com/google/android/gms/tasks/CancellationTokenSource) that creates it. It can only be canceled once. If canceled, it should not be passed to future operations.\n\nWhen [cancel](/android/reference/kotlin/com/google/android/gms/tasks/CancellationTokenSource#cancel()) is called, all the Tasks with the `\nCancellationToken` from that [CancellationTokenSource](/android/reference/kotlin/com/google/android/gms/tasks/CancellationTokenSource) will be canceled. This operation only flags those Tasks as canceled, and the API author is responsible for stopping whatever the Task is actually doing to free up the resources.\n\nCancellable [Task](/android/reference/kotlin/com/google/android/gms/tasks/Task) example: \n\n```kotlin\npublic Task\u003cInteger\u003e doSomething(CancellationToken token) {\n\n // Attach a listener that will be called once cancellation is requested.\n token.onCanceledRequested(new OnTokenCanceledListener() {\n @Override\n public void onCanceled() {\n // Some other operations to cancel this Task, such as free resources...\n }\n });\n\n final TaskCompletionSource\u003cInteger\u003e tcs = new TaskCompletionSource\u003c\u003e(token);\n\n // do something...\n\n}\n\nCancellationTokenSource cts = new CancellationTokenSource();\nTask\u003cInteger\u003e task = doSomething(cts.getToken());\ncts.cancel();\n```\nCancellable [Task](/android/reference/kotlin/com/google/android/gms/tasks/Task) example in [android.app.Activity](https://developer.android.com/reference/android/app/Activity.html) context: \n\n```kotlin\npublic class MyActivity extends Activity {\n // ...\n\n @Override\n public void onStart() {\n super.onStart();\n\n // Typically use one cancellation source per lifecycle.\n cancellationSource = new CancellationTokenSource();\n\n // That source's token can be passed to multiple calls.\n doSomethingCancellable(cancellationSource.getToken())\n .onSuccessTask(result -\u003e doSomethingElse(result, cancellationSource.getToken()));\n }\n\n @Override\n public void onStop() {\n super.onStop();\n cancellationSource.cancel();\n }\n}\n```\n\nSummary\n-------\n\n| ### Public constructors |\n|-----------------------------------------------------------------------------------------------------------------------|\n| [CancellationToken](/android/reference/kotlin/com/google/android/gms/tasks/CancellationToken#CancellationToken())`()` |\n\n| ### Public functions |\n|----------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| `abstract `[Boolean](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-boolean/index.html) | [isCancellationRequested](/android/reference/kotlin/com/google/android/gms/tasks/CancellationToken#isCancellationRequested())`()` Checks if cancellation has been requested from the [CancellationTokenSource](/android/reference/kotlin/com/google/android/gms/tasks/CancellationTokenSource). |\n| `abstract `[CancellationToken](/android/reference/kotlin/com/google/android/gms/tasks/CancellationToken) | [onCanceledRequested](/android/reference/kotlin/com/google/android/gms/tasks/CancellationToken#onCanceledRequested(com.google.android.gms.tasks.OnTokenCanceledListener))`(listener: `[OnTokenCanceledListener](/android/reference/kotlin/com/google/android/gms/tasks/OnTokenCanceledListener)`)` Adds an [OnTokenCanceledListener](/android/reference/kotlin/com/google/android/gms/tasks/OnTokenCanceledListener) to this [CancellationToken](/android/reference/kotlin/com/google/android/gms/tasks/CancellationToken). |\n\nPublic constructors\n-------------------\n\n### CancellationToken\n\n```\nCancellationToken()\n``` \n\nPublic functions\n----------------\n\n### isCancellationRequested\n\n```\nabstract fun isCancellationRequested(): Boolean\n```\n\nChecks if cancellation has been requested from the [CancellationTokenSource](/android/reference/kotlin/com/google/android/gms/tasks/CancellationTokenSource). \n\n| Returns |\n|------------------------------------------------------------------------------------|--------------------------------------------------------|\n| [Boolean](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-boolean/index.html) | `true` if cancellation is requested, `false` otherwise |\n\n### onCanceledRequested\n\n```\nabstract fun onCanceledRequested(listener: OnTokenCanceledListener): CancellationToken\n```\n\nAdds an [OnTokenCanceledListener](/android/reference/kotlin/com/google/android/gms/tasks/OnTokenCanceledListener) to this [CancellationToken](/android/reference/kotlin/com/google/android/gms/tasks/CancellationToken). \n\n| Parameters |\n|-----------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------|\n| `listener: `[OnTokenCanceledListener](/android/reference/kotlin/com/google/android/gms/tasks/OnTokenCanceledListener) | the listener that will fire once the cancellation request succeeds. |"]]
