From: Eugene Susla <eugenesusla@google.com>
Date: Fri, 15 Dec 2017 23:53:40 +0000 (-0800)
Subject: Add a 'unbounded method refs only' clause to PooledLambda javadoc
X-Git-Tag: android-x86-9.0-r1~280^2~11^2
X-Git-Url: http://git.osdn.net/view?a=commitdiff_plain;h=de8ca1ef94a82add0a5fa7c7dc923b8a5992a0e6;p=android-x86%2Fframeworks-base.git

Add a 'unbounded method refs only' clause to PooledLambda javadoc

Test: proofread
Change-Id: I26f1ac6e61289769a75a629b7b2057d32237a560
---

diff --git a/core/java/com/android/internal/util/function/pooled/PooledLambda.java b/core/java/com/android/internal/util/function/pooled/PooledLambda.java
index 17b140dec396..87c25e9663d8 100755
--- a/core/java/com/android/internal/util/function/pooled/PooledLambda.java
+++ b/core/java/com/android/internal/util/function/pooled/PooledLambda.java
@@ -59,6 +59,21 @@ import java.util.function.Supplier;
  * You can fill the 'missing argument' spot with {@link #__()}
  * (which is the factory function for {@link ArgumentPlaceholder})
  *
+ * NOTE: It is highly recommended to <b>only</b> use {@code ClassName::methodName}
+ * (aka unbounded method references) as the 1st argument for any of the
+ * factories ({@code obtain*(...)}) to avoid unwanted allocations.
+ * This means <b>not</b> using:
+ * <ul>
+ *     <li>{@code someVar::methodName} or {@code this::methodName} as it captures the reference
+ *     on the left of {@code ::}, resulting in an allocation on each evaluation of such
+ *     bounded method references</li>
+ *
+ *     <li>A lambda expression, e.g. {@code () -> toString()} due to how easy it is to accidentally
+ *     capture state from outside. In the above lambda expression for example, no variable from
+ *     outer scope is explicitly mentioned, yet one is still captured due to {@code toString()}
+ *     being an equivalent of {@code this.toString()}</li>
+ * </ul>
+ *
  * @hide
  */
 @SuppressWarnings({"unchecked", "unused", "WeakerAccess"})