diff options
author | Tor Norbye <tnorbye@google.com> | 2018-11-29 08:23:45 -0800 |
---|---|---|
committer | android-build-merger <android-build-merger@google.com> | 2018-11-29 08:23:45 -0800 |
commit | 6632e99d3ddd9b3aec0b5b1e131938801f2bf588 (patch) | |
tree | 0fa83bb442073804df0d14e7cb0cbcb9f14e7fe9 | |
parent | d65d594cc246a242a1aeb92404a415c0e8734895 (diff) | |
parent | d39248f05d5ac365134cc14897f8937f50174426 (diff) | |
download | support-6632e99d3ddd9b3aec0b5b1e131938801f2bf588.tar.gz |
Merge "Improve documentation for thread annotations."
am: d39248f05d
Change-Id: I7e7d7377e6266768413fd6458b1b205b5df2c054
5 files changed, 191 insertions, 26 deletions
diff --git a/annotations/src/main/java/androidx/annotation/AnyThread.java b/annotations/src/main/java/androidx/annotation/AnyThread.java index e3144454c90..c33fc3fed34 100644 --- a/annotations/src/main/java/androidx/annotation/AnyThread.java +++ b/annotations/src/main/java/androidx/annotation/AnyThread.java @@ -27,18 +27,51 @@ import java.lang.annotation.Target; /** * Denotes that the annotated method can be called from any thread (e.g. it is "thread safe".) - * If the annotated element is a class, then all methods in the class can be called - * from any thread. * <p> - * The main purpose of this method is to indicate that you believe a method can be called + * The main purpose of this annotation is to indicate that you believe a method can be called * from any thread; static tools can then check that nothing you call from within this method * or class have more strict threading requirements. - * <p> - * Example: * <pre><code> * @AnyThread * public void deliverResult(D data) { ... } * </code></pre> + * + * <p>If the annotated element is a class, then all methods in the class can be called + * from any thread. </p> + * + * <pre><code> + * @AnyThread + * public class Foo { ... } + * </code></pre> + * + * <p>When the class is annotated, but one of the methods has another threading annotation such as + * {@link MainThread}, the method annotation takes precedence. In the following example, + * <code>onResult()</code> should only be called on the main thread.</p> + * + * <pre><code> + * @AnyThread + * public class Foo { + * @MainThread + * void onResult(String result) { ... } + * } + * </code></pre> + * + * <p>Multiple threading annotations can be combined. Following example illustrates that, + * <code>saveUser()</code> can be called on a worker thread or the main thread. + * It's safe for <code>saveUser()</code> to invoke <code>isEmpty()</code>, whereas it's not safe + * for <code>isEmpty()</code> to invoke <code>saveUser()</code>. + * </p> + * + * <pre><code> + * public class Foo { + * @WorkerThread + * @MainThread + * void saveUser(User user) { ... } + * + * @AnyThread + * boolean isEmpty(String value) { ... } + * } + * </code></pre> */ @Documented @Retention(CLASS) diff --git a/annotations/src/main/java/androidx/annotation/BinderThread.java b/annotations/src/main/java/androidx/annotation/BinderThread.java index 2f944a9df45..92a426b2239 100644 --- a/annotations/src/main/java/androidx/annotation/BinderThread.java +++ b/annotations/src/main/java/androidx/annotation/BinderThread.java @@ -27,14 +27,47 @@ import java.lang.annotation.Target; /** * Denotes that the annotated method should only be called on the binder thread. - * If the annotated element is a class, then all methods in the class should be called - * on the binder thread. - * <p> - * Example: * <pre><code> * @BinderThread * public BeamShareData createBeamShareData() { ... } * </code></pre> + * + * <p>If the annotated element is a class, then all methods in the class should be called + * on the binder thread. </p> + * + * <pre><code> + * @BinderThread + * public class Foo { ... } + * </code></pre> + * + * <p>When the class is annotated, but one of the methods has another threading annotation such as + * {@link UiThread}, the method annotation takes precedence. In the following example, + * <code>setText()</code> should be called on the UI thread.</p> + * + * <pre><code> + * @BinderThread + * public class Foo { + * @UiThread + * void setText(String text) { ... } + * } + * </code></pre> + * + * <p>Multiple threading annotations can be combined. Following example illustrates that, + * <code>isEmpty()</code> can be called on a worker thread or the binder thread. + * It's safe for <code>saveUser()</code> to invoke <code>isEmpty()</code>, whereas it's not safe + * for <code>isEmpty()</code> to invoke <code>saveUser()</code>. + * </p> + * + * <pre><code> + * public class Foo { + * @WorkerThread + * void saveUser(User user) { ... } + * + * @WorkerThread + * @BinderThread + * boolean isEmpty(String value) { ... } + * } + * </code></pre> */ @Documented @Retention(CLASS) diff --git a/annotations/src/main/java/androidx/annotation/MainThread.java b/annotations/src/main/java/androidx/annotation/MainThread.java index fe5404803d4..d1599d4c765 100644 --- a/annotations/src/main/java/androidx/annotation/MainThread.java +++ b/annotations/src/main/java/androidx/annotation/MainThread.java @@ -27,17 +27,51 @@ import java.lang.annotation.Target; /** * Denotes that the annotated method should only be called on the main thread. - * If the annotated element is a class, then all methods in the class should be called - * on the main thread. - * <p> - * Example: + * + * <pre><code> + * @MainThread + * void deliverResult(D data) { ... } + * </code></pre> + * + * <p>If the annotated element is a class, then all methods in the class should be called + * on the main thread. </p> + * + * <pre><code> + * @MainThread + * public class Foo { ... } + * </code></pre> + * + * <p>When the class is annotated, but one of the methods has another threading annotation such as + * {@link WorkerThread}, the method annotation takes precedence. In the following example, + * <code>getUser()</code> should be called on a worker thread.</p> + * * <pre><code> * @MainThread - * public void deliverResult(D data) { ... } + * public class Foo { + * @WorkerThread + * User getUser() { ... } + * } + * </code></pre> + * + * <p>Multiple threading annotations can be combined. Following example illustrates that, + * <code>isEmpty()</code> can be called on a worker thread or the main thread. + * It's safe for <code>saveUser()</code> to invoke <code>isEmpty()</code>, whereas it's not safe + * for <code>isEmpty()</code> to invoke <code>saveUser()</code>. + * </p> + * + * <pre><code> + * public class Foo { + * @WorkerThread + * void saveUser(User user) { ... } + * + * @WorkerThread + * @MainThread + * boolean isEmpty(String value) { ... } + * } * </code></pre> * * <p class="note"><b>Note:</b> Ordinarily, an app's main thread is also the UI - * thread. However, However, under special circumstances, an app's main thread + * thread. However, under special circumstances, an app's main thread * might not be its UI thread; for more information, see * <a href="/studio/write/annotations.html#thread-annotations">Thread * annotations</a>. diff --git a/annotations/src/main/java/androidx/annotation/UiThread.java b/annotations/src/main/java/androidx/annotation/UiThread.java index f08290f3962..fdf647924c2 100644 --- a/annotations/src/main/java/androidx/annotation/UiThread.java +++ b/annotations/src/main/java/androidx/annotation/UiThread.java @@ -27,18 +27,50 @@ import java.lang.annotation.Target; /** * Denotes that the annotated method or constructor should only be called on the UI thread. - * If the annotated element is a class, then all methods in the class should be called - * on the UI thread. - * <p> - * Example: * <pre><code> * @UiThread + * void setText(@NonNull String text) { ... } + * </code></pre> + * + * <p>If the annotated element is a class, then all methods in the class should be called + * on the UI thread. </p> + * + * <pre><code> + * @UiThread + * public class Foo { ... } + * </code></pre> + * + * <p>When the class is annotated, but one of the methods has another threading annotation such as + * {@link WorkerThread}, the method annotation takes precedence. In the following example, + * <code>getUser()</code> should be called on a worker thread.</p> + * + * <pre><code> + * @UiThread + * public class Foo { + * @WorkerThread + * User getUser() { ... } + * } + * </code></pre> + * + * <p>Multiple threading annotations can be combined. Following example illustrates that, + * <code>isEmpty()</code> can be called on a worker thread or the main thread. + * It's safe for <code>saveUser()</code> to invoke <code>isEmpty()</code>, whereas it's not safe + * for <code>isEmpty()</code> to invoke <code>saveUser()</code>. + * </p> + * + * <pre><code> + * public class Foo { + * @WorkerThread + * void saveUser(User user) { ... } * - * public abstract void setText(@NonNull String text) { ... } + * @WorkerThread + * @UiThread + * boolean isEmpty(String value) { ... } + * } * </code></pre> * * <p class="note"><b>Note:</b> Ordinarily, an app's UI thread is also the main - * thread. However, However, under special circumstances, an app's UI thread + * thread. However, under special circumstances, an app's UI thread * might not be its main thread; for more information, see * <a href="/studio/write/annotations.html#thread-annotations">Thread * annotations</a>. diff --git a/annotations/src/main/java/androidx/annotation/WorkerThread.java b/annotations/src/main/java/androidx/annotation/WorkerThread.java index f1023018b45..ac88dfb7622 100644 --- a/annotations/src/main/java/androidx/annotation/WorkerThread.java +++ b/annotations/src/main/java/androidx/annotation/WorkerThread.java @@ -27,13 +27,46 @@ import java.lang.annotation.Target; /** * Denotes that the annotated method should only be called on a worker thread. - * If the annotated element is a class, then all methods in the class should be called - * on a worker thread. - * <p> - * Example: * <pre><code> * @WorkerThread - * protected abstract FilterResults performFiltering(CharSequence constraint); + * FilterResults performFiltering(CharSequence constraint); + * </code></pre> + * + * <p>If the annotated element is a class, then all methods in the class should be called + * on a worker thread. </p> + * + * <pre><code> + * @WorkerThread + * public class Foo { ... } + * </code></pre> + * + * <p>When the class is annotated, but one of the methods has another threading annotation such as + * {@link MainThread}, the method annotation takes precedence. In the following example, + * <code>onResult()</code> should be called on the main thread.</p> + * + * <pre><code> + * @WorkerThread + * public class Foo { + * @MainThread + * void onResult(String result) { ... } + * } + * </code></pre> + * + * <p>Multiple threading annotations can be combined. Following example illustrates that, + * <code>isEmpty()</code> can be called on the worker thread or the main thread. + * It's safe for <code>saveUser()</code> to invoke <code>isEmpty()</code>, whereas it's not safe + * for <code>isEmpty()</code> to invoke <code>saveUser()</code>. + * </p> + * + * <pre><code> + * public class Foo { + * @WorkerThread + * void saveUser(User user) { ... } + * + * @WorkerThread + * @UiThread + * boolean isEmpty(String value) { ... } + * } * </code></pre> */ @Documented |