From d72e4724074b513734c115ba619f259fe3464062 Mon Sep 17 00:00:00 2001 From: Hans Boehm Date: Fri, 29 Apr 2022 11:09:16 -0700 Subject: [PATCH] Document VirtualRefBasePtr hazards Test: Treehugger Change-Id: I6f364b4e0f73a2eb554f2902a67e774ef5890b00 --- .../android/internal/util/VirtualRefBasePtr.java | 13 ++++++++++++- 1 file changed, 12 insertions(+), 1 deletion(-) diff --git a/core/java/com/android/internal/util/VirtualRefBasePtr.java b/core/java/com/android/internal/util/VirtualRefBasePtr.java index 52306f1f877e5..13ddc0602609c 100644 --- a/core/java/com/android/internal/util/VirtualRefBasePtr.java +++ b/core/java/com/android/internal/util/VirtualRefBasePtr.java @@ -18,9 +18,12 @@ package com.android.internal.util; /** * Helper class that contains a strong reference to a VirtualRefBase native - * object. This will incStrong in the ctor, and decStrong in the finalizer + * object. This will incStrong in the ctor, and decStrong in the finalizer. + * It currently does no accounting of natively allocated memory, for the + * benefit of either GC triggering or heap profiling. */ public final class VirtualRefBasePtr { + // TODO(b/231729094): Convert to NativeAllocationRegistry? private long mNativePtr; public VirtualRefBasePtr(long ptr) { @@ -28,6 +31,14 @@ public final class VirtualRefBasePtr { nIncStrong(mNativePtr); } + /* + * Return the RefBase / VirtualLightRefBase native pointer. Warning: The + * caller must ensure that the VirtualRefBasePtr object remains reachable + * while the result is in use. Ideally, the caller should invoke + * {@link java.lang.ref.Reference#reachabilityFence} + * on the VirtualRefBasePtr object (or on an object that refers to it) as + * soon as the result is no longer needed. + */ public long get() { return mNativePtr; }