2 // ========================================================================
3 // Copyright (c) 1995-2016 Mort Bay Consulting Pty. Ltd.
4 // ------------------------------------------------------------------------
5 // All rights reserved. This program and the accompanying materials
6 // are made available under the terms of the Eclipse Public License v1.0
7 // and Apache License v2.0 which accompanies this distribution.
9 // The Eclipse Public License is available at
10 // http://www.eclipse.org/legal/epl-v10.html
12 // The Apache License v2.0 is available at
13 // http://www.opensource.org/licenses/apache2.0.php
15 // You may elect to redistribute this code under either of these licenses.
16 // ========================================================================
19 package org.eclipse.jetty.util;
21 import java.lang.ref.PhantomReference;
22 import java.lang.ref.ReferenceQueue;
23 import java.lang.ref.WeakReference;
24 import java.util.concurrent.ConcurrentHashMap;
25 import java.util.concurrent.ConcurrentMap;
27 import org.eclipse.jetty.util.component.AbstractLifeCycle;
28 import org.eclipse.jetty.util.log.Log;
29 import org.eclipse.jetty.util.log.Logger;
32 * A facility to detect improper usage of resource pools.
34 * Resource pools usually have a method to acquire a pooled resource and a method to released it back to the pool.
36 * To detect if client code acquires a resource but never releases it, the resource pool can be modified to use a
37 * {@link LeakDetector}. The modified resource pool should call {@link #acquired(Object)} every time the method to
38 * acquire a resource is called, and {@link #released(Object)} every time the method to release the resource is called.
39 * {@link LeakDetector} keeps track of these resources and invokes method
40 * {@link #leaked(org.eclipse.jetty.util.LeakDetector.LeakInfo)} when it detects that a resource has been leaked (that
41 * is, acquired but never released).
43 * To detect whether client code releases a resource without having acquired it, the resource pool can be modified to
44 * check the return value of {@link #released(Object)}: if false, it means that the resource was not acquired.
46 * IMPLEMENTATION NOTES
48 * This class relies on {@link System#identityHashCode(Object)} to create a unique id for each resource passed to
49 * {@link #acquired(Object)} and {@link #released(Object)}. {@link System#identityHashCode(Object)} does not guarantee
50 * that it will not generate the same number for different objects, but in practice the chance of collision is rare.
52 * {@link LeakDetector} uses {@link PhantomReference}s to detect leaks. {@link PhantomReference}s are enqueued in their
53 * {@link ReferenceQueue} <em>after</em> they have been garbage collected (differently from {@link WeakReference}s that
54 * are enqueued <em>before</em>). Since the resource is now garbage collected, {@link LeakDetector} checks whether it
55 * has been released and if not, it reports a leak. Using {@link PhantomReference}s is better than overriding
56 * {@link #finalize()} and works also in those cases where {@link #finalize()} is not overridable.
58 * @param <T> the resource type.
60 public class LeakDetector<T> extends AbstractLifeCycle implements Runnable
62 private static final Logger LOG = Log.getLogger(LeakDetector.class);
64 private final ReferenceQueue<T> queue = new ReferenceQueue<>();
65 private final ConcurrentMap<String, LeakInfo> resources = new ConcurrentHashMap<>();
66 private Thread thread;
69 * Tracks the resource as been acquired.
71 * @param resource the resource that has been acquired
72 * @return true whether the resource has been acquired normally, false if the resource has detected a leak (meaning
73 * that another acquire occurred before a release of the same resource)
74 * @see #released(Object)
76 public boolean acquired(T resource)
78 String id = id(resource);
79 LeakInfo info = resources.putIfAbsent(id, new LeakInfo(resource,id));
82 // Leak detected, prior acquire exists (not released) or id clash.
90 * Tracks the resource as been released.
92 * @param resource the resource that has been released
93 * @return true whether the resource has been released normally (based on a previous acquire). false if the resource
94 * has been released without a prior acquire (such as a double release scenario)
95 * @see #acquired(Object)
97 public boolean released(T resource)
99 String id = id(resource);
100 LeakInfo info = resources.remove(id);
107 // Leak detected (released without acquire).
112 * Generates a unique ID for the given resource.
114 * @param resource the resource to generate the unique ID for
115 * @return the unique ID of the given resource
117 public String id(T resource)
119 return String.valueOf(System.identityHashCode(resource));
123 protected void doStart() throws Exception
126 thread = new Thread(this,getClass().getSimpleName());
127 thread.setDaemon(true);
132 protected void doStop() throws Exception
145 @SuppressWarnings("unchecked")
146 LeakInfo leakInfo = (LeakInfo)queue.remove();
147 if (LOG.isDebugEnabled())
148 LOG.debug("Resource GC'ed: {}",leakInfo);
149 if (resources.remove(leakInfo.id) != null)
153 catch (InterruptedException x)
160 * Callback method invoked by {@link LeakDetector} when it detects that a resource has been leaked.
162 * @param leakInfo the information about the leak
164 protected void leaked(LeakInfo leakInfo)
166 LOG.warn("Resource leaked: " + leakInfo.description,leakInfo.stackFrames);
170 * Information about the leak of a resource.
172 public class LeakInfo extends PhantomReference<T>
174 private final String id;
175 private final String description;
176 private final Throwable stackFrames;
178 private LeakInfo(T referent, String id)
180 super(referent,queue);
182 this.description = referent.toString();
183 this.stackFrames = new Throwable();
187 * @return the resource description as provided by the resource's {@link Object#toString()} method.
189 public String getResourceDescription()
195 * @return a Throwable instance that contains the stack frames at the time of resource acquisition.
197 public Throwable getStackFrames()
203 public String toString()