1 /* 2 * Copyright (C) 2010 The Android Open Source Project 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17 package dalvik.system; 18 19 /** 20 * A no-op copy of libcore/dalvik/src/main/java/dalvik/system/CloseGuard.java 21 */ 22 public final class CloseGuard { 23 24 /** 25 * Returns a CloseGuard instance. {@code #open(String)} can be used to set 26 * up the instance to warn on failure to close. 27 * 28 * @return {@link CloseGuard} instance. 29 * 30 * @hide 31 */ get()32 public static CloseGuard get() { 33 return new CloseGuard(); 34 } 35 36 /** 37 * Enables/disables stack capture and tracking. A call stack is captured 38 * during open(), and open/close events are reported to the Tracker, only 39 * if enabled is true. If a stack trace was captured, the {@link 40 * #getReporter() reporter} is informed of unclosed resources; otherwise a 41 * one-line warning is logged. 42 * 43 * @param enabled whether stack capture and tracking is enabled. 44 * 45 * @hide 46 */ setEnabled(boolean enabled)47 public static void setEnabled(boolean enabled) { 48 } 49 50 /** 51 * True if CloseGuard stack capture and tracking are enabled. 52 * 53 * @hide 54 */ isEnabled()55 public static boolean isEnabled() { 56 return false; 57 } 58 59 /** 60 * Used to replace default Reporter used to warn of CloseGuard 61 * violations when stack tracking is enabled. Must be non-null. 62 * 63 * @param rep replacement for default Reporter. 64 * 65 * @hide 66 */ setReporter(Reporter rep)67 public static void setReporter(Reporter rep) { 68 if (rep == null) { 69 throw new NullPointerException("reporter == null"); 70 } 71 } 72 73 /** 74 * Returns non-null CloseGuard.Reporter. 75 * 76 * @return CloseGuard's Reporter. 77 * 78 * @hide 79 */ getReporter()80 public static Reporter getReporter() { 81 return null; 82 } 83 84 /** 85 * Sets the {@link Tracker} that is notified when resources are allocated and released. 86 * The Tracker is invoked only if CloseGuard {@link #isEnabled()} held when {@link #open()} 87 * was called. A null argument disables tracking. 88 * 89 * <p>This is only intended for use by {@code dalvik.system.CloseGuardSupport} class and so 90 * MUST NOT be used for any other purposes. 91 * 92 * @hide 93 */ setTracker(Tracker tracker)94 public static void setTracker(Tracker tracker) { 95 } 96 97 /** 98 * Returns {@link #setTracker(Tracker) last Tracker that was set}, or null to indicate 99 * there is none. 100 * 101 * <p>This is only intended for use by {@code dalvik.system.CloseGuardSupport} class and so 102 * MUST NOT be used for any other purposes. 103 * 104 * @hide 105 */ getTracker()106 public static Tracker getTracker() { 107 return null; 108 } 109 CloseGuard()110 private CloseGuard() {} 111 112 /** 113 * {@code open} initializes the instance with a warning that the caller 114 * should have explicitly called the {@code closer} method instead of 115 * relying on finalization. 116 * 117 * @param closer non-null name of explicit termination method. Printed by warnIfOpen. 118 * @throws NullPointerException if closer is null. 119 * 120 * @hide 121 */ open(String closer)122 public void open(String closer) { 123 openWithCallSite(closer, null /* callsite */); 124 } 125 126 /** 127 * Like {@link #open(String)}, but with explicit callsite string being passed in for better 128 * performance. 129 * <p> 130 * This only has better performance than {@link #open(String)} if {@link #isEnabled()} returns {@code true}, which 131 * usually shouldn't happen on release builds. 132 * 133 * @param closer Non-null name of explicit termination method. Printed by warnIfOpen. 134 * @param callsite Non-null string uniquely identifying the callsite. 135 * 136 * @hide 137 */ openWithCallSite(String closer, String callsite)138 public void openWithCallSite(String closer, String callsite) { 139 } 140 141 // We keep either an allocation stack containing the closer String or, when 142 // in disabled state, just the closer String. 143 // We keep them in a single field only to minimize overhead. 144 private Object /* String or Throwable */ closerNameOrAllocationInfo; 145 146 /** 147 * Marks this CloseGuard instance as closed to avoid warnings on 148 * finalization. 149 * 150 * @hide 151 */ close()152 public void close() { 153 } 154 155 /** 156 * Logs a warning if the caller did not properly cleanup by calling an 157 * explicit close method before finalization. If CloseGuard was enabled 158 * when the CloseGuard was created, passes the stacktrace associated with 159 * the allocation to the current reporter. If it was not enabled, it just 160 * directly logs a brief message. 161 * 162 * @hide 163 */ warnIfOpen()164 public void warnIfOpen() { 165 } 166 167 168 /** 169 * Interface to allow customization of tracking behaviour. 170 * 171 * <p>This is only intended for use by {@code dalvik.system.CloseGuardSupport} class and so 172 * MUST NOT be used for any other purposes. 173 * 174 * @hide 175 */ 176 public interface Tracker { open(Throwable allocationSite)177 void open(Throwable allocationSite); close(Throwable allocationSite)178 void close(Throwable allocationSite); 179 } 180 181 /** 182 * Interface to allow customization of reporting behavior. 183 * @hide 184 */ 185 public interface Reporter { 186 /** 187 * 188 * @hide 189 */ report(String message, Throwable allocationSite)190 void report(String message, Throwable allocationSite); 191 192 /** 193 * 194 * @hide 195 */ report(String message)196 default void report(String message) {} 197 } 198 } 199