From ab02e0b1cb2e82c55a4bade4825a6c758b76ad0d Mon Sep 17 00:00:00 2001
From: Shuzhen Wang <shuzhenwang@google.com>
Date: Thu, 5 Jan 2023 11:58:42 -0800
Subject: [PATCH] Camera: Clarify doc for registerAvailabilityCallback

Camera availability callbacks's order matter. If the application runs
the callbacks on an executor, and the executor is implemented using
multiple threads, the order of the callbacks may change.

Test: Build and read docs
Bug: 263235259
Change-Id: I88913215e0545a096958aaba6b7b2b7d73a4f0a0
---
 .../android/hardware/camera2/CameraManager.java | 17 +++++++++++++++++
 1 file changed, 17 insertions(+)

diff --git a/core/java/android/hardware/camera2/CameraManager.java b/core/java/android/hardware/camera2/CameraManager.java
index d6d3a97687b5c..8eeca24712213 100644
--- a/core/java/android/hardware/camera2/CameraManager.java
+++ b/core/java/android/hardware/camera2/CameraManager.java
@@ -364,6 +364,23 @@ public final class CameraManager {
      * except that it uses {@link java.util.concurrent.Executor} as an argument
      * instead of {@link android.os.Handler}.</p>
      *
+     * <p>Note: If the order between some availability callbacks matters, the implementation of the
+     * executor should handle those callbacks in the same thread to maintain the callbacks' order.
+     * Some examples are:</p>
+     *
+     * <ul>
+     *
+     * <li>{@link AvailabilityCallback#onCameraAvailable} and
+     * {@link AvailabilityCallback#onCameraUnavailable} of the same camera ID.</li>
+     *
+     * <li>{@link AvailabilityCallback#onCameraAvailable} or
+     * {@link AvailabilityCallback#onCameraUnavailable} of a logical multi-camera, and {@link
+     * AvailabilityCallback#onPhysicalCameraUnavailable} or
+     * {@link AvailabilityCallback#onPhysicalCameraAvailable} of its physical
+     * cameras.</li>
+     *
+     * </ul>
+     *
      * @param executor The executor which will be used to invoke the callback.
      * @param callback the new callback to send camera availability notices to
      *