Bug 9060: Minor [Java|inline] doc update re. getStackTrace() performance

Change-Id: I4f1ab259b79154f7abc8df2d28d5ecb2ad18ef98
Signed-off-by: Michael Vorburger <vorburger@redhat.com>

diff --git a/opendaylight/md-sal/mdsal-trace/dom-impl/src/main/java/org/opendaylight/controller/md/sal/trace/closetracker/impl/CloseTracked.java b/opendaylight/md-sal/mdsal-trace/dom-impl/src/main/java/org/opendaylight/controller/md/sal/trace/closetracker/impl/CloseTracked.java
index 926c8b3b8ee5e69dfb4a221bcafb5c815b257e7b..ef42c4025c6232494ff1f9a92048edfb7189ae5e 100644 (file)
--- a/opendaylight/md-sal/mdsal-trace/dom-impl/src/main/java/org/opendaylight/controller/md/sal/trace/closetracker/impl/CloseTracked.java
+++ b/opendaylight/md-sal/mdsal-trace/dom-impl/src/main/java/org/opendaylight/controller/md/sal/trace/closetracker/impl/CloseTracked.java
@@ -18,6 +18,13 @@ import javax.annotation.Nullable;
  */
 public interface CloseTracked<T extends CloseTracked<T>> {
 
+    /**
+     * This returns the allocation context as {@link StackTraceElement}s. NB that
+     * this is a relatively <b>EXPENSIVE</b> operation! You should only ever call
+     * this when you really need to, e.g. when you actually produce output for
+     * humans, but not too early.
+     */
+    // TODO When we're on Java 9, then instead return a StackWalker.StackFrame[] here?
     @Nullable StackTraceElement[] getAllocationContextStackTrace();
 
     CloseTracked<T> getRealCloseTracked();

diff --git a/opendaylight/md-sal/mdsal-trace/dom-impl/src/main/java/org/opendaylight/controller/md/sal/trace/closetracker/impl/CloseTrackedTrait.java b/opendaylight/md-sal/mdsal-trace/dom-impl/src/main/java/org/opendaylight/controller/md/sal/trace/closetracker/impl/CloseTrackedTrait.java
index b1b41319e5527610cf84eb649bcf9db669b099e2..4fe1e12ec8e83288c5339cbe9b3e1fec8a3df01e 100644 (file)
--- a/opendaylight/md-sal/mdsal-trace/dom-impl/src/main/java/org/opendaylight/controller/md/sal/trace/closetracker/impl/CloseTrackedTrait.java
+++ b/opendaylight/md-sal/mdsal-trace/dom-impl/src/main/java/org/opendaylight/controller/md/sal/trace/closetracker/impl/CloseTrackedTrait.java
@@ -22,13 +22,19 @@ import javax.annotation.Nullable;
  */
 public class CloseTrackedTrait<T extends CloseTracked<T>> implements CloseTracked<T> {
 
+    // NB: It's important that we keep a Throwable here, and not directly the StackTraceElement[] !
+    // This is because creating a new Throwable() is a lot less expensive in terms of runtime overhead
+    // than actually calling its getStackTrace(), which we can delay until we really need to.
+    // see also e.g. https://stackoverflow.com/a/26122232/421602
     private final @Nullable Throwable allocationContext;
     private final CloseTrackedRegistry<T> closeTrackedRegistry;
     private final CloseTracked<T> realCloseTracked;
 
     public CloseTrackedTrait(CloseTrackedRegistry<T> transactionChainRegistry, CloseTracked<T> realCloseTracked) {
         if (transactionChainRegistry.isDebugContextEnabled()) {
-            this.allocationContext = new Throwable("allocated at");
+            // NB: We're NOT doing the (expensive) getStackTrace() here just yet (only below)
+            // TODO When we're on Java 9, then instead use the new java.lang.StackWalker API..
+            this.allocationContext = new Throwable();
         } else {
             this.allocationContext = null;
         }
@@ -38,6 +44,7 @@ public class CloseTrackedTrait<T extends CloseTracked<T>> implements CloseTracke
     }
 
     @Override
+    @Nullable
     public StackTraceElement[] getAllocationContextStackTrace() {
         return allocationContext != null ? allocationContext.getStackTrace() : null;
     }