Better lifecycle for async callbacks

Author: trask

api/all/src/main/java/io/opentelemetry/api/metrics/DoubleCounterBuilder.java

@@ -5,6 +5,7 @@
 
 package io.opentelemetry.api.metrics;
 
+import java.util.function.BiConsumer;
 import java.util.function.Consumer;
 
 /**
@@ -56,6 +57,34 @@ public interface DoubleCounterBuilder {
    */
   ObservableDoubleCounter buildWithCallback(Consumer<ObservableDoubleMeasurement> callback);
 
+  /**
+   * Builds an Asynchronous Counter instrument with the given callback.
+   *
+   * <p>The callback will be called when the instrument is being observed, with {@code obj} passed
+   * as the first argument. This allows the SDK to hold a weak reference to {@code obj}, enabling
+   * automatic cleanup when the measured object is garbage collected.
+   *
+   * <p>The {@code obj} should be an independently-rooted object that the application holds for its
+   * own purposes (e.g. a connection pool, service instance, or cache). When the application drops
+   * its strong reference to {@code obj}, the SDK may automatically remove the callback.
+   *
+   * <p>Callbacks are expected to abide by the following restrictions:
+   *
+   * <ul>
+   *   <li>Run in a finite amount of time.
+   *   <li>Safe to call repeatedly, across multiple threads.
+   * </ul>
+   *
+   * @param obj The measured object. The callback receives this as its first argument.
+   * @param callback A callback which observes measurements when invoked.
+   * @param <T> The type of the measured object.
+   */
+  @SuppressWarnings("InconsistentOverloads")
+  default <T> ObservableDoubleCounter buildWithCallback(
+      T obj, BiConsumer<T, ObservableDoubleMeasurement> callback) {
+    return buildWithCallback(measurement -> callback.accept(obj, measurement));
+  }
+
   /**
    * Build an observer for this instrument to observe values from a {@link BatchCallback}.
    *

api/all/src/main/java/io/opentelemetry/api/metrics/DoubleGaugeBuilder.java

@@ -5,6 +5,7 @@
 
 package io.opentelemetry.api.metrics;
 
+import java.util.function.BiConsumer;
 import java.util.function.Consumer;
 
 /**
@@ -52,6 +53,34 @@ public interface DoubleGaugeBuilder {
    */
   ObservableDoubleGauge buildWithCallback(Consumer<ObservableDoubleMeasurement> callback);
 
+  /**
+   * Builds an Asynchronous Gauge instrument with the given callback.
+   *
+   * <p>The callback will be called when the instrument is being observed, with {@code obj} passed
+   * as the first argument. This allows the SDK to hold a weak reference to {@code obj}, enabling
+   * automatic cleanup when the measured object is garbage collected.
+   *
+   * <p>The {@code obj} should be an independently-rooted object that the application holds for its
+   * own purposes (e.g. a connection pool, service instance, or cache). When the application drops
+   * its strong reference to {@code obj}, the SDK may automatically remove the callback.
+   *
+   * <p>Callbacks are expected to abide by the following restrictions:
+   *
+   * <ul>
+   *   <li>Run in a finite amount of time.
+   *   <li>Safe to call repeatedly, across multiple threads.
+   * </ul>
+   *
+   * @param obj The measured object. The callback receives this as its first argument.
+   * @param callback A callback which observes measurements when invoked.
+   * @param <T> The type of the measured object.
+   */
+  @SuppressWarnings("InconsistentOverloads")
+  default <T> ObservableDoubleGauge buildWithCallback(
+      T obj, BiConsumer<T, ObservableDoubleMeasurement> callback) {
+    return buildWithCallback(measurement -> callback.accept(obj, measurement));
+  }
+
   /**
    * Build an observer for this instrument to observe values from a {@link BatchCallback}.
    *

api/all/src/main/java/io/opentelemetry/api/metrics/DoubleUpDownCounterBuilder.java

@@ -5,6 +5,7 @@
 
 package io.opentelemetry.api.metrics;
 
+import java.util.function.BiConsumer;
 import java.util.function.Consumer;
 
 /**
@@ -56,6 +57,34 @@ public interface DoubleUpDownCounterBuilder {
    */
   ObservableDoubleUpDownCounter buildWithCallback(Consumer<ObservableDoubleMeasurement> callback);
 
+  /**
+   * Builds an Asynchronous UpDownCounter instrument with the given callback.
+   *
+   * <p>The callback will be called when the instrument is being observed, with {@code obj} passed
+   * as the first argument. This allows the SDK to hold a weak reference to {@code obj}, enabling
+   * automatic cleanup when the measured object is garbage collected.
+   *
+   * <p>The {@code obj} should be an independently-rooted object that the application holds for its
+   * own purposes (e.g. a connection pool, service instance, or cache). When the application drops
+   * its strong reference to {@code obj}, the SDK may automatically remove the callback.
+   *
+   * <p>Callbacks are expected to abide by the following restrictions:
+   *
+   * <ul>
+   *   <li>Run in a finite amount of time.
+   *   <li>Safe to call repeatedly, across multiple threads.
+   * </ul>
+   *
+   * @param obj The measured object. The callback receives this as its first argument.
+   * @param callback A callback which observes measurements when invoked.
+   * @param <T> The type of the measured object.
+   */
+  @SuppressWarnings("InconsistentOverloads")
+  default <T> ObservableDoubleUpDownCounter buildWithCallback(
+      T obj, BiConsumer<T, ObservableDoubleMeasurement> callback) {
+    return buildWithCallback(measurement -> callback.accept(obj, measurement));
+  }
+
   /**
    * Build an observer for this instrument to observe values from a {@link BatchCallback}.
    *

api/all/src/main/java/io/opentelemetry/api/metrics/LongCounterBuilder.java

@@ -5,6 +5,7 @@
 
 package io.opentelemetry.api.metrics;
 
+import java.util.function.BiConsumer;
 import java.util.function.Consumer;
 
 /**
@@ -60,6 +61,34 @@ public interface LongCounterBuilder {
    */
   ObservableLongCounter buildWithCallback(Consumer<ObservableLongMeasurement> callback);
 
+  /**
+   * Builds an Asynchronous Counter instrument with the given callback.
+   *
+   * <p>The callback will be called when the instrument is being observed, with {@code obj} passed
+   * as the first argument. This allows the SDK to hold a weak reference to {@code obj}, enabling
+   * automatic cleanup when the measured object is garbage collected.
+   *
+   * <p>The {@code obj} should be an independently-rooted object that the application holds for its
+   * own purposes (e.g. a connection pool, service instance, or cache). When the application drops
+   * its strong reference to {@code obj}, the SDK may automatically remove the callback.
+   *
+   * <p>Callbacks are expected to abide by the following restrictions:
+   *
+   * <ul>
+   *   <li>Run in a finite amount of time.
+   *   <li>Safe to call repeatedly, across multiple threads.
+   * </ul>
+   *
+   * @param obj The measured object. The callback receives this as its first argument.
+   * @param callback A callback which observes measurements when invoked.
+   * @param <T> The type of the measured object.
+   */
+  @SuppressWarnings("InconsistentOverloads")
+  default <T> ObservableLongCounter buildWithCallback(
+      T obj, BiConsumer<T, ObservableLongMeasurement> callback) {
+    return buildWithCallback(measurement -> callback.accept(obj, measurement));
+  }
+
   /**
    * Build an observer for this instrument to observe values from a {@link BatchCallback}.
    *

api/all/src/main/java/io/opentelemetry/api/metrics/LongGaugeBuilder.java

@@ -5,6 +5,7 @@
 
 package io.opentelemetry.api.metrics;
 
+import java.util.function.BiConsumer;
 import java.util.function.Consumer;
 
 /**
@@ -49,6 +50,34 @@ public interface LongGaugeBuilder {
    */
   ObservableLongGauge buildWithCallback(Consumer<ObservableLongMeasurement> callback);
 
+  /**
+   * Builds an Asynchronous Gauge instrument with the given callback.
+   *
+   * <p>The callback will be called when the instrument is being observed, with {@code obj} passed
+   * as the first argument. This allows the SDK to hold a weak reference to {@code obj}, enabling
+   * automatic cleanup when the measured object is garbage collected.
+   *
+   * <p>The {@code obj} should be an independently-rooted object that the application holds for its
+   * own purposes (e.g. a connection pool, service instance, or cache). When the application drops
+   * its strong reference to {@code obj}, the SDK may automatically remove the callback.
+   *
+   * <p>Callbacks are expected to abide by the following restrictions:
+   *
+   * <ul>
+   *   <li>Run in a finite amount of time.
+   *   <li>Safe to call repeatedly, across multiple threads.
+   * </ul>
+   *
+   * @param obj The measured object. The callback receives this as its first argument.
+   * @param callback A callback which observes measurements when invoked.
+   * @param <T> The type of the measured object.
+   */
+  @SuppressWarnings("InconsistentOverloads")
+  default <T> ObservableLongGauge buildWithCallback(
+      T obj, BiConsumer<T, ObservableLongMeasurement> callback) {
+    return buildWithCallback(measurement -> callback.accept(obj, measurement));
+  }
+
   /**
    * Build an observer for this instrument to observe values from a {@link BatchCallback}.
    *

api/all/src/main/java/io/opentelemetry/api/metrics/LongUpDownCounterBuilder.java

@@ -5,6 +5,7 @@
 
 package io.opentelemetry.api.metrics;
 
+import java.util.function.BiConsumer;
 import java.util.function.Consumer;
 
 /**
@@ -59,6 +60,34 @@ public interface LongUpDownCounterBuilder {
    */
   ObservableLongUpDownCounter buildWithCallback(Consumer<ObservableLongMeasurement> callback);
 
+  /**
+   * Builds an Asynchronous UpDownCounter instrument with the given callback.
+   *
+   * <p>The callback will be called when the instrument is being observed, with {@code obj} passed
+   * as the first argument. This allows the SDK to hold a weak reference to {@code obj}, enabling
+   * automatic cleanup when the measured object is garbage collected.
+   *
+   * <p>The {@code obj} should be an independently-rooted object that the application holds for its
+   * own purposes (e.g. a connection pool, service instance, or cache). When the application drops
+   * its strong reference to {@code obj}, the SDK may automatically remove the callback.
+   *
+   * <p>Callbacks are expected to abide by the following restrictions:
+   *
+   * <ul>
+   *   <li>Run in a finite amount of time.
+   *   <li>Safe to call repeatedly, across multiple threads.
+   * </ul>
+   *
+   * @param obj The measured object. The callback receives this as its first argument.
+   * @param callback A callback which observes measurements when invoked.
+   * @param <T> The type of the measured object.
+   */
+  @SuppressWarnings("InconsistentOverloads")
+  default <T> ObservableLongUpDownCounter buildWithCallback(
+      T obj, BiConsumer<T, ObservableLongMeasurement> callback) {
+    return buildWithCallback(measurement -> callback.accept(obj, measurement));
+  }
+
   /**
    * Build an observer for this instrument to observe values from a {@link BatchCallback}.
    *

api/all/src/main/java/io/opentelemetry/api/metrics/Meter.java

@@ -5,6 +5,7 @@
 
 package io.opentelemetry.api.metrics;
 
+import java.util.function.Consumer;
 import javax.annotation.concurrent.ThreadSafe;
 
 /**
@@ -145,4 +146,39 @@ default BatchCallback batchCallback(
     return DefaultMeter.getInstance()
         .batchCallback(callback, observableMeasurement, additionalMeasurements);
   }
+
+  /**
+   * Creates a batch callback with the given measured object.
+   *
+   * <p>The callback will be called when the instruments are being observed, with {@code obj} passed
+   * as the argument. This allows the SDK to hold a weak reference to {@code obj}, enabling
+   * automatic cleanup when the measured object is garbage collected.
+   *
+   * <p>The {@code obj} should be an independently-rooted object that the application holds for its
+   * own purposes (e.g. a connection pool, service instance, or cache). When the application drops
+   * its strong reference to {@code obj}, the SDK may automatically remove the callback.
+   *
+   * <p>Callbacks are expected to abide by the following restrictions:
+   *
+   * <ul>
+   *   <li>Run in a finite amount of time.
+   *   <li>Safe to call repeatedly, across multiple threads.
+   *   <li>Only observe values to registered instruments (i.e. {@code observableMeasurement} and
+   *       {@code additionalMeasurements}
+   * </ul>
+   *
+   * @param obj The measured object. The callback receives this as its argument.
+   * @param callback a callback used to observe values on-demand.
+   * @param observableMeasurement Instruments for which the callback may observe values.
+   * @param additionalMeasurements Instruments for which the callback may observe values.
+   * @param <T> The type of the measured object.
+   */
+  @SuppressWarnings("InconsistentOverloads")
+  default <T> BatchCallback batchCallback(
+      T obj,
+      Consumer<T> callback,
+      ObservableMeasurement observableMeasurement,
+      ObservableMeasurement... additionalMeasurements) {
+    return batchCallback(() -> callback.accept(obj), observableMeasurement, additionalMeasurements);
+  }
 }