Update refresh rate callback docs to include DisplayManager caveat.
Display#getRefreshRate is eventually consistent, so callbacks that call into DisplayManager may misbehave without polling, which is brittle. This will not be fixed until Android 12 at the earliest, so document this for Android 11.
Bug: 161725670
Change-Id: I0557c1e18747ee69eba5ea39c6e974873bdee5a0
diff --git a/include/android/choreographer.h b/include/android/choreographer.h
index bdf11e4..e9f559c 100644
--- a/include/android/choreographer.h
+++ b/include/android/choreographer.h
@@ -130,6 +130,13 @@
* This api is thread-safe. Any thread is allowed to register a new refresh
* rate callback for the choreographer instance.
*
+ * Note that in API level 30, this api is not guaranteed to be atomic with
+ * DisplayManager. That is, calling Display#getRefreshRate very soon after
+ * a refresh rate callback is invoked may return a stale refresh rate. If any
+ * Display properties would be required by this callback, then it is recommended
+ * to listen directly to DisplayManager.DisplayListener#onDisplayChanged events
+ * instead.
+ *
* Available since API level 30.
*/
void AChoreographer_registerRefreshRateCallback(AChoreographer* choreographer,