Rename handle to bound instrument (@sircelsius) (#400)

* Rename metric Handle to Bound Instrument

* Rename metric Handle to Bound Instrument

* Rename metric Handle to Bound Instrument

* chore(meter): renamed from *BoundInstrument to Bound*, renamed AcquireBoundInstrument to Bind

* chore(meter): renamed Release to Unbind

* Self feedback in doc.go

* Rename confusing method name

Co-authored-by: Marc Bramaud <sircelsius@users.noreply.github.com>

api/global/internal/meter.go

@@ -85,7 +85,7 @@ var _ metric.Meter = &meter{}
 var _ metric.LabelSet = &labelSet{}
 var _ metric.LabelSetDelegate = &labelSet{}
 var _ metric.InstrumentImpl = &instImpl{}
-var _ metric.HandleImpl = &instHandle{}
+var _ metric.BoundInstrumentImpl = &instHandle{}
 
 // Provider interface and delegation
 
@@ -181,9 +181,9 @@ func (inst *instImpl) setDelegate(d metric.Meter) {
 	atomic.StorePointer(&inst.delegate, unsafe.Pointer(implPtr))
 }
 
-func (inst *instImpl) AcquireHandle(labels metric.LabelSet) metric.HandleImpl {
+func (inst *instImpl) Bind(labels metric.LabelSet) metric.BoundInstrumentImpl {
 	if implPtr := (*metric.InstrumentImpl)(atomic.LoadPointer(&inst.delegate)); implPtr != nil {
-		return (*implPtr).AcquireHandle(labels)
+		return (*implPtr).Bind(labels)
 	}
 	return &instHandle{
 		inst:   inst,
@@ -191,16 +191,16 @@ func (inst *instImpl) AcquireHandle(labels metric.LabelSet) metric.HandleImpl {
 	}
 }
 
-func (bound *instHandle) Release() {
+func (bound *instHandle) Unbind() {
 	bound.initialize.Do(func() {})
 
-	implPtr := (*metric.HandleImpl)(atomic.LoadPointer(&bound.delegate))
+	implPtr := (*metric.BoundInstrumentImpl)(atomic.LoadPointer(&bound.delegate))
 
 	if implPtr == nil {
 		return
 	}
 
-	(*implPtr).Release()
+	(*implPtr).Unbind()
 }
 
 // Metric updates
@@ -224,15 +224,14 @@ func (bound *instHandle) RecordOne(ctx context.Context, number core.Number) {
 	if instPtr == nil {
 		return
 	}
-	var implPtr *metric.HandleImpl
+	var implPtr *metric.BoundInstrumentImpl
 	bound.initialize.Do(func() {
-
-		implPtr = new(metric.HandleImpl)
-		*implPtr = (*instPtr).AcquireHandle(bound.labels)
+		implPtr = new(metric.BoundInstrumentImpl)
+		*implPtr = (*instPtr).Bind(bound.labels)
 		atomic.StorePointer(&bound.delegate, unsafe.Pointer(implPtr))
 	})
 	if implPtr == nil {
-		implPtr = (*metric.HandleImpl)(atomic.LoadPointer(&bound.delegate))
+		implPtr = (*metric.BoundInstrumentImpl)(atomic.LoadPointer(&bound.delegate))
 	}
 	(*implPtr).RecordOne(ctx, number)
 }

api/global/internal/meter_test.go

@@ -114,17 +114,17 @@ func TestBound(t *testing.T) {
 	labels2 := glob.Labels(lvals2)
 
 	counter := glob.NewFloat64Counter("test.counter")
-	boundC := counter.AcquireHandle(labels1)
+	boundC := counter.Bind(labels1)
 	boundC.Add(ctx, 1)
 	boundC.Add(ctx, 1)
 
 	gauge := glob.NewFloat64Gauge("test.gauge")
-	boundG := gauge.AcquireHandle(labels2)
+	boundG := gauge.Bind(labels2)
 	boundG.Set(ctx, 1)
 	boundG.Set(ctx, 2)
 
 	measure := glob.NewInt64Measure("test.measure")
-	boundM := measure.AcquireHandle(labels1)
+	boundM := measure.Bind(labels1)
 	boundM.Record(ctx, 1)
 	boundM.Record(ctx, 2)
 
@@ -165,13 +165,13 @@ func TestBound(t *testing.T) {
 	require.Equal(t, "test.measure",
 		mock.MeasurementBatches[2].Measurements[0].Instrument.Name)
 
-	boundC.Release()
-	boundG.Release()
-	boundM.Release()
+	boundC.Unbind()
+	boundG.Unbind()
+	boundM.Unbind()
 }
 
-func TestRelease(t *testing.T) {
-	// Tests Release with SDK never installed.
+func TestUnbind(t *testing.T) {
+	// Tests Unbind with SDK never installed.
 	internal.ResetForTest()
 
 	glob := global.MeterProvider().Meter("test")
@@ -181,17 +181,17 @@ func TestRelease(t *testing.T) {
 	labels2 := glob.Labels(lvals2)
 
 	counter := glob.NewFloat64Counter("test.counter")
-	boundC := counter.AcquireHandle(labels1)
+	boundC := counter.Bind(labels1)
 
 	gauge := glob.NewFloat64Gauge("test.gauge")
-	boundG := gauge.AcquireHandle(labels2)
+	boundG := gauge.Bind(labels2)
 
 	measure := glob.NewInt64Measure("test.measure")
-	boundM := measure.AcquireHandle(labels1)
+	boundM := measure.Bind(labels1)
 
-	boundC.Release()
-	boundG.Release()
-	boundM.Release()
+	boundC.Unbind()
+	boundG.Unbind()
+	boundM.Unbind()
 }
 
 func TestDefaultSDK(t *testing.T) {

api/metric/api_test.go

@@ -374,8 +374,8 @@ func TestCounter(t *testing.T) {
 		ctx := context.Background()
 		labels := meter.Labels()
 		c.Add(ctx, 42, labels)
-		handle := c.AcquireHandle(labels)
-		handle.Add(ctx, 42)
+		boundInstrument := c.Bind(labels)
+		boundInstrument.Add(ctx, 42)
 		meter.RecordBatch(ctx, labels, c.Measurement(42))
 		t.Log("Testing float counter")
 		checkBatches(t, ctx, labels, meter, core.Float64NumberKind, c.Impl())
@@ -386,8 +386,8 @@ func TestCounter(t *testing.T) {
 		ctx := context.Background()
 		labels := meter.Labels()
 		c.Add(ctx, 42, labels)
-		handle := c.AcquireHandle(labels)
-		handle.Add(ctx, 42)
+		boundInstrument := c.Bind(labels)
+		boundInstrument.Add(ctx, 42)
 		meter.RecordBatch(ctx, labels, c.Measurement(42))
 		t.Log("Testing int counter")
 		checkBatches(t, ctx, labels, meter, core.Int64NumberKind, c.Impl())
@@ -401,8 +401,8 @@ func TestGauge(t *testing.T) {
 		ctx := context.Background()
 		labels := meter.Labels()
 		g.Set(ctx, 42, labels)
-		handle := g.AcquireHandle(labels)
-		handle.Set(ctx, 42)
+		boundInstrument := g.Bind(labels)
+		boundInstrument.Set(ctx, 42)
 		meter.RecordBatch(ctx, labels, g.Measurement(42))
 		t.Log("Testing float gauge")
 		checkBatches(t, ctx, labels, meter, core.Float64NumberKind, g.Impl())
@@ -413,8 +413,8 @@ func TestGauge(t *testing.T) {
 		ctx := context.Background()
 		labels := meter.Labels()
 		g.Set(ctx, 42, labels)
-		handle := g.AcquireHandle(labels)
-		handle.Set(ctx, 42)
+		boundInstrument := g.Bind(labels)
+		boundInstrument.Set(ctx, 42)
 		meter.RecordBatch(ctx, labels, g.Measurement(42))
 		t.Log("Testing int gauge")
 		checkBatches(t, ctx, labels, meter, core.Int64NumberKind, g.Impl())
@@ -428,8 +428,8 @@ func TestMeasure(t *testing.T) {
 		ctx := context.Background()
 		labels := meter.Labels()
 		m.Record(ctx, 42, labels)
-		handle := m.AcquireHandle(labels)
-		handle.Record(ctx, 42)
+		boundInstrument := m.Bind(labels)
+		boundInstrument.Record(ctx, 42)
 		meter.RecordBatch(ctx, labels, m.Measurement(42))
 		t.Log("Testing float measure")
 		checkBatches(t, ctx, labels, meter, core.Float64NumberKind, m.Impl())
@@ -440,8 +440,8 @@ func TestMeasure(t *testing.T) {
 		ctx := context.Background()
 		labels := meter.Labels()
 		m.Record(ctx, 42, labels)
-		handle := m.AcquireHandle(labels)
-		handle.Record(ctx, 42)
+		boundInstrument := m.Bind(labels)
+		boundInstrument.Record(ctx, 42)
 		meter.RecordBatch(ctx, labels, m.Measurement(42))
 		t.Log("Testing int measure")
 		checkBatches(t, ctx, labels, meter, core.Int64NumberKind, m.Impl())

api/metric/common.go

@@ -24,12 +24,12 @@ type commonMetric struct {
 	instrument InstrumentImpl
 }
 
-type commonHandle struct {
-	handle HandleImpl
+type commonBoundInstrument struct {
+	boundInstrument BoundInstrumentImpl
 }
 
-func (m commonMetric) acquireCommonHandle(labels LabelSet) commonHandle {
-	return newCommonHandle(m.instrument.AcquireHandle(labels))
+func (m commonMetric) bind(labels LabelSet) commonBoundInstrument {
+	return newCommonBoundInstrument(m.instrument.Bind(labels))
 }
 
 func (m commonMetric) float64Measurement(value float64) Measurement {
@@ -40,7 +40,7 @@ func (m commonMetric) int64Measurement(value int64) Measurement {
 	return newMeasurement(m.instrument, core.NewInt64Number(value))
 }
 
-func (m commonMetric) recordOne(ctx context.Context, number core.Number, labels LabelSet) {
+func (m commonMetric) directRecord(ctx context.Context, number core.Number, labels LabelSet) {
 	m.instrument.RecordOne(ctx, number, labels)
 }
 
@@ -48,12 +48,12 @@ func (m commonMetric) Impl() InstrumentImpl {
 	return m.instrument
 }
 
-func (h commonHandle) recordOne(ctx context.Context, number core.Number) {
-	h.handle.RecordOne(ctx, number)
+func (h commonBoundInstrument) directRecord(ctx context.Context, number core.Number) {
+	h.boundInstrument.RecordOne(ctx, number)
 }
 
-func (h commonHandle) Release() {
-	h.handle.Release()
+func (h commonBoundInstrument) Unbind() {
+	h.boundInstrument.Unbind()
 }
 
 func newCommonMetric(instrument InstrumentImpl) commonMetric {
@@ -62,9 +62,9 @@ func newCommonMetric(instrument InstrumentImpl) commonMetric {
 	}
 }
 
-func newCommonHandle(handle HandleImpl) commonHandle {
-	return commonHandle{
-		handle: handle,
+func newCommonBoundInstrument(boundInstrument BoundInstrumentImpl) commonBoundInstrument {
+	return commonBoundInstrument{
+		boundInstrument: boundInstrument,
 	}
 }
 

api/metric/counter.go

@@ -30,41 +30,41 @@ type Int64Counter struct {
 	commonMetric
 }
 
-// Float64CounterHandle is a handle for Float64Counter.
+// BoundFloat64Counter is a bound instrument for Float64Counter.
 //
-// It inherits the Release function from commonHandle.
-type Float64CounterHandle struct {
-	commonHandle
+// It inherits the Unbind function from commonBoundInstrument.
+type BoundFloat64Counter struct {
+	commonBoundInstrument
 }
 
-// Int64CounterHandle is a handle for Int64Counter.
+// BoundInt64Counter is a boundInstrument for Int64Counter.
 //
-// It inherits the Release function from commonHandle.
-type Int64CounterHandle struct {
-	commonHandle
+// It inherits the Unbind function from commonBoundInstrument.
+type BoundInt64Counter struct {
+	commonBoundInstrument
 }
 
-// AcquireHandle creates a handle for this counter. The labels should
+// Bind creates a bound instrument for this counter. The labels should
 // contain the keys and values for each key specified in the counter
 // with the WithKeys option.
 //
 // If the labels do not contain a value for the key specified in the
 // counter with the WithKeys option, then the missing value will be
 // treated as unspecified.
-func (c *Float64Counter) AcquireHandle(labels LabelSet) (h Float64CounterHandle) {
-	h.commonHandle = c.acquireCommonHandle(labels)
+func (c *Float64Counter) Bind(labels LabelSet) (h BoundFloat64Counter) {
+	h.commonBoundInstrument = c.bind(labels)
 	return
 }
 
-// AcquireHandle creates a handle for this counter. The labels should
+// Bind creates a bound instrument for this counter. The labels should
 // contain the keys and values for each key specified in the counter
 // with the WithKeys option.
 //
 // If the labels do not contain a value for the key specified in the
 // counter with the WithKeys option, then the missing value will be
 // treated as unspecified.
-func (c *Int64Counter) AcquireHandle(labels LabelSet) (h Int64CounterHandle) {
-	h.commonHandle = c.acquireCommonHandle(labels)
+func (c *Int64Counter) Bind(labels LabelSet) (h BoundInt64Counter) {
+	h.commonBoundInstrument = c.bind(labels)
 	return
 }
 
@@ -88,7 +88,7 @@ func (c *Int64Counter) Measurement(value int64) Measurement {
 // counter with the WithKeys option, then the missing value will be
 // treated as unspecified.
 func (c *Float64Counter) Add(ctx context.Context, value float64, labels LabelSet) {
-	c.recordOne(ctx, core.NewFloat64Number(value), labels)
+	c.directRecord(ctx, core.NewFloat64Number(value), labels)
 }
 
 // Add adds the value to the counter's sum. The labels should contain
@@ -99,15 +99,15 @@ func (c *Float64Counter) Add(ctx context.Context, value float64, labels LabelSet
 // counter with the WithKeys option, then the missing value will be
 // treated as unspecified.
 func (c *Int64Counter) Add(ctx context.Context, value int64, labels LabelSet) {
-	c.recordOne(ctx, core.NewInt64Number(value), labels)
+	c.directRecord(ctx, core.NewInt64Number(value), labels)
 }
 
 // Add adds the value to the counter's sum.
-func (h *Float64CounterHandle) Add(ctx context.Context, value float64) {
-	h.recordOne(ctx, core.NewFloat64Number(value))
+func (b *BoundFloat64Counter) Add(ctx context.Context, value float64) {
+	b.directRecord(ctx, core.NewFloat64Number(value))
 }
 
 // Add adds the value to the counter's sum.
-func (h *Int64CounterHandle) Add(ctx context.Context, value int64) {
-	h.recordOne(ctx, core.NewInt64Number(value))
+func (b *BoundInt64Counter) Add(ctx context.Context, value int64) {
+	b.directRecord(ctx, core.NewInt64Number(value))
 }

api/metric/doc.go

@@ -27,7 +27,7 @@
 // The primary object that handles metrics is Meter. The
 // implementation of the Meter is provided by SDK. Normally, the Meter
 // is used directly only for the LabelSet generation, batch recording
-// and the handle destruction.
+// and the bound instrument destruction.
 //
 // LabelSet is a set of keys and values that are in a suitable,
 // optimized form to be used by Meter.
@@ -60,10 +60,11 @@
 // the New*Measure function - this allows reporting negative values
 // too. To report a new value, use the Record function.
 //
-// All the basic kinds of instruments also support creating handles
-// for a potentially more efficient reporting. The handles have the
-// same function names as the instruments (so counter handle has Add,
-// gauge handle has Set and measure handle has Record). Handles can be
-// created with the AcquireHandle function of the respective
-// instrument. When done with the handle, call Release on it.
+// All the basic kinds of instruments also support creating bound
+// instruments for a potentially more efficient reporting. The bound
+// instruments have the same function names as the instruments (so a
+// Counter bound instrument has Add, a Gauge bound instrument has Set,
+// and a Measure bound instrument has Record).  Bound Instruments can
+// be created with the Bind function of the respective
+// instrument. When done with the bound instrument, call Unbind on it.
 package metric // import "go.opentelemetry.io/otel/api/metric"

api/metric/gauge.go

@@ -30,41 +30,41 @@ type Int64Gauge struct {
 	commonMetric
 }
 
-// Float64GaugeHandle is a handle for Float64Gauge.
+// BoundFloat64Gauge is a bound instrument for Float64Gauge.
 //
-// It inherits the Release function from commonHandle.
-type Float64GaugeHandle struct {
-	commonHandle
+// It inherits the Unbind function from commonBoundInstrument.
+type BoundFloat64Gauge struct {
+	commonBoundInstrument
 }
 
-// Int64GaugeHandle is a handle for Int64Gauge.
+// BoundInt64Gauge is a bound instrument for Int64Gauge.
 //
-// It inherits the Release function from commonHandle.
-type Int64GaugeHandle struct {
-	commonHandle
+// It inherits the Unbind function from commonBoundInstrument.
+type BoundInt64Gauge struct {
+	commonBoundInstrument
 }
 
-// AcquireHandle creates a handle for this gauge. The labels should
+// Bind creates a bound instrument for this gauge. The labels should
 // contain the keys and values for each key specified in the gauge
 // with the WithKeys option.
 //
 // If the labels do not contain a value for the key specified in the
 // gauge with the WithKeys option, then the missing value will be
 // treated as unspecified.
-func (g *Float64Gauge) AcquireHandle(labels LabelSet) (h Float64GaugeHandle) {
-	h.commonHandle = g.acquireCommonHandle(labels)
+func (g *Float64Gauge) Bind(labels LabelSet) (h BoundFloat64Gauge) {
+	h.commonBoundInstrument = g.bind(labels)
 	return
 }
 
-// AcquireHandle creates a handle for this gauge. The labels should
+// Bind creates a bound instrument for this gauge. The labels should
 // contain the keys and values for each key specified in the gauge
 // with the WithKeys option.
 //
 // If the labels do not contain a value for the key specified in the
 // gauge with the WithKeys option, then the missing value will be
 // treated as unspecified.
-func (g *Int64Gauge) AcquireHandle(labels LabelSet) (h Int64GaugeHandle) {
-	h.commonHandle = g.acquireCommonHandle(labels)
+func (g *Int64Gauge) Bind(labels LabelSet) (h BoundInt64Gauge) {
+	h.commonBoundInstrument = g.bind(labels)
 	return
 }
 
@@ -88,7 +88,7 @@ func (g *Int64Gauge) Measurement(value int64) Measurement {
 // gauge with the WithKeys option, then the missing value will be
 // treated as unspecified.
 func (g *Float64Gauge) Set(ctx context.Context, value float64, labels LabelSet) {
-	g.recordOne(ctx, core.NewFloat64Number(value), labels)
+	g.directRecord(ctx, core.NewFloat64Number(value), labels)
 }
 
 // Set assigns the passed value to the value of the gauge. The labels
@@ -99,15 +99,15 @@ func (g *Float64Gauge) Set(ctx context.Context, value float64, labels LabelSet)
 // gauge with the WithKeys option, then the missing value will be
 // treated as unspecified.
 func (g *Int64Gauge) Set(ctx context.Context, value int64, labels LabelSet) {
-	g.recordOne(ctx, core.NewInt64Number(value), labels)
+	g.directRecord(ctx, core.NewInt64Number(value), labels)
 }
 
 // Set assigns the passed value to the value of the gauge.
-func (h *Float64GaugeHandle) Set(ctx context.Context, value float64) {
-	h.recordOne(ctx, core.NewFloat64Number(value))
+func (b *BoundFloat64Gauge) Set(ctx context.Context, value float64) {
+	b.directRecord(ctx, core.NewFloat64Number(value))
 }
 
 // Set assigns the passed value to the value of the gauge.
-func (h *Int64GaugeHandle) Set(ctx context.Context, value int64) {
-	h.recordOne(ctx, core.NewInt64Number(value))
+func (b *BoundInt64Gauge) Set(ctx context.Context, value int64) {
+	b.directRecord(ctx, core.NewInt64Number(value))
 }

api/metric/measure.go

@@ -30,41 +30,41 @@ type Int64Measure struct {
 	commonMetric
 }
 
-// Float64MeasureHandle is a handle for Float64Measure.
+// BoundFloat64Measure is a bound instrument for Float64Measure.
 //
-// It inherits the Release function from commonHandle.
-type Float64MeasureHandle struct {
-	commonHandle
+// It inherits the Unbind function from commonBoundInstrument.
+type BoundFloat64Measure struct {
+	commonBoundInstrument
 }
 
-// Int64MeasureHandle is a handle for Int64Measure.
+// BoundInt64Measure is a bound instrument for Int64Measure.
 //
-// It inherits the Release function from commonHandle.
-type Int64MeasureHandle struct {
-	commonHandle
+// It inherits the Unbind function from commonBoundInstrument.
+type BoundInt64Measure struct {
+	commonBoundInstrument
 }
 
-// AcquireHandle creates a handle for this measure. The labels should
+// Bind creates a bound instrument for this measure. The labels should
 // contain the keys and values for each key specified in the measure
 // with the WithKeys option.
 //
 // If the labels do not contain a value for the key specified in the
 // measure with the WithKeys option, then the missing value will be
 // treated as unspecified.
-func (c *Float64Measure) AcquireHandle(labels LabelSet) (h Float64MeasureHandle) {
-	h.commonHandle = c.acquireCommonHandle(labels)
+func (c *Float64Measure) Bind(labels LabelSet) (h BoundFloat64Measure) {
+	h.commonBoundInstrument = c.bind(labels)
 	return
 }
 
-// AcquireHandle creates a handle for this measure. The labels should
+// Bind creates a bound instrument for this measure. The labels should
 // contain the keys and values for each key specified in the measure
 // with the WithKeys option.
 //
 // If the labels do not contain a value for the key specified in the
 // measure with the WithKeys option, then the missing value will be
 // treated as unspecified.
-func (c *Int64Measure) AcquireHandle(labels LabelSet) (h Int64MeasureHandle) {
-	h.commonHandle = c.acquireCommonHandle(labels)
+func (c *Int64Measure) Bind(labels LabelSet) (h BoundInt64Measure) {
+	h.commonBoundInstrument = c.bind(labels)
 	return
 }
 
@@ -88,7 +88,7 @@ func (c *Int64Measure) Measurement(value int64) Measurement {
 // measure with the WithKeys option, then the missing value will be
 // treated as unspecified.
 func (c *Float64Measure) Record(ctx context.Context, value float64, labels LabelSet) {
-	c.recordOne(ctx, core.NewFloat64Number(value), labels)
+	c.directRecord(ctx, core.NewFloat64Number(value), labels)
 }
 
 // Record adds a new value to the list of measure's records. The
@@ -99,15 +99,15 @@ func (c *Float64Measure) Record(ctx context.Context, value float64, labels Label
 // measure with the WithKeys option, then the missing value will be
 // treated as unspecified.
 func (c *Int64Measure) Record(ctx context.Context, value int64, labels LabelSet) {
-	c.recordOne(ctx, core.NewInt64Number(value), labels)
+	c.directRecord(ctx, core.NewInt64Number(value), labels)
 }
 
 // Record adds a new value to the list of measure's records.
-func (h *Float64MeasureHandle) Record(ctx context.Context, value float64) {
-	h.recordOne(ctx, core.NewFloat64Number(value))
+func (b *BoundFloat64Measure) Record(ctx context.Context, value float64) {
+	b.directRecord(ctx, core.NewFloat64Number(value))
 }
 
 // Record adds a new value to the list of measure's records.
-func (h *Int64MeasureHandle) Record(ctx context.Context, value int64) {
-	h.recordOne(ctx, core.NewInt64Number(value))
+func (b *BoundInt64Measure) Record(ctx context.Context, value int64) {
+	b.directRecord(ctx, core.NewInt64Number(value))
 }

api/metric/noop.go

@@ -8,28 +8,28 @@ import (
 
 type NoopProvider struct{}
 type NoopMeter struct{}
-type noopHandle struct{}
+type noopBoundInstrument struct{}
 type noopLabelSet struct{}
 type noopInstrument struct{}
 
 var _ Provider = NoopProvider{}
 var _ Meter = NoopMeter{}
 var _ InstrumentImpl = noopInstrument{}
-var _ HandleImpl = noopHandle{}
+var _ BoundInstrumentImpl = noopBoundInstrument{}
 var _ LabelSet = noopLabelSet{}
 
 func (NoopProvider) Meter(name string) Meter {
 	return NoopMeter{}
 }
 
-func (noopHandle) RecordOne(context.Context, core.Number) {
+func (noopBoundInstrument) RecordOne(context.Context, core.Number) {
 }
 
-func (noopHandle) Release() {
+func (noopBoundInstrument) Unbind() {
 }
 
-func (noopInstrument) AcquireHandle(LabelSet) HandleImpl {
-	return noopHandle{}
+func (noopInstrument) Bind(LabelSet) BoundInstrumentImpl {
+	return noopBoundInstrument{}
 }
 
 func (noopInstrument) RecordOne(context.Context, core.Number, LabelSet) {

api/metric/sdkhelpers.go

@@ -32,23 +32,23 @@ type LabelSetDelegate interface {
 // InstrumentImpl is the implementation-level interface Set/Add/Record
 // individual metrics without precomputed labels.
 type InstrumentImpl interface {
-	// AcquireHandle creates a Handle to record metrics with
+	// Bind creates a Bound Instrument to record metrics with
 	// precomputed labels.
-	AcquireHandle(labels LabelSet) HandleImpl
+	Bind(labels LabelSet) BoundInstrumentImpl
 
 	// RecordOne allows the SDK to observe a single metric event.
 	RecordOne(ctx context.Context, number core.Number, labels LabelSet)
 }
 
-// HandleImpl is the implementation-level interface to Set/Add/Record
+// BoundInstrumentImpl is the implementation-level interface to Set/Add/Record
 // individual metrics with precomputed labels.
-type HandleImpl interface {
+type BoundInstrumentImpl interface {
 	// RecordOne allows the SDK to observe a single metric event.
 	RecordOne(ctx context.Context, number core.Number)
 
-	// Release frees the resources associated with this handle. It
-	// does not affect the metric this handle was created through.
-	Release()
+	// Unbind frees the resources associated with this bound instrument. It
+	// does not affect the metric this bound instrument was created through.
+	Unbind()
 }
 
 // WrapInt64CounterInstrument wraps the instrument in the type-safe

example/basic/main.go

@@ -99,11 +99,11 @@ func main() {
 
 	commonLabels := meter.Labels(lemonsKey.Int(10), key.String("A", "1"), key.String("B", "2"), key.String("C", "3"))
 
-	gauge := oneMetric.AcquireHandle(commonLabels)
-	defer gauge.Release()
+	gauge := oneMetric.Bind(commonLabels)
+	defer gauge.Unbind()
 
-	measure := measureTwo.AcquireHandle(commonLabels)
-	defer measure.Release()
+	measure := measureTwo.Bind(commonLabels)
+	defer measure.Unbind()
 
 	err := tracer.WithSpan(ctx, "operation", func(ctx context.Context) error {
 

internal/metric/mock.go

@@ -64,10 +64,10 @@ type (
 )
 
 var (
-	_ apimetric.InstrumentImpl = &Instrument{}
-	_ apimetric.HandleImpl     = &Handle{}
-	_ apimetric.LabelSet       = &LabelSet{}
-	_ apimetric.Meter          = &Meter{}
+	_ apimetric.InstrumentImpl      = &Instrument{}
+	_ apimetric.BoundInstrumentImpl = &Handle{}
+	_ apimetric.LabelSet            = &LabelSet{}
+	_ apimetric.Meter               = &Meter{}
 )
 
 const (
@@ -76,7 +76,7 @@ const (
 	KindMeasure
 )
 
-func (i *Instrument) AcquireHandle(labels apimetric.LabelSet) apimetric.HandleImpl {
+func (i *Instrument) Bind(labels apimetric.LabelSet) apimetric.BoundInstrumentImpl {
 	if ld, ok := labels.(apimetric.LabelSetDelegate); ok {
 		labels = ld.Delegate()
 	}
@@ -97,7 +97,7 @@ func (h *Handle) RecordOne(ctx context.Context, number core.Number) {
 	doRecordBatch(ctx, h.LabelSet, h.Instrument, number)
 }
 
-func (h *Handle) Release() {
+func (h *Handle) Unbind() {
 }
 
 func doRecordBatch(ctx context.Context, labelSet *LabelSet, instrument *Instrument, number core.Number) {

sdk/metric/benchmark_test.go

@@ -149,7 +149,7 @@ func BenchmarkAcquireNewHandle(b *testing.B) {
 	b.ResetTimer()
 
 	for i := 0; i < b.N; i++ {
-		cnt.AcquireHandle(labels[i])
+		cnt.Bind(labels[i])
 	}
 }
 
@@ -161,13 +161,13 @@ func BenchmarkAcquireExistingHandle(b *testing.B) {
 
 	for i := 0; i < b.N; i++ {
 		labels[i] = fix.sdk.Labels(labelSets[i]...)
-		cnt.AcquireHandle(labels[i]).Release()
+		cnt.Bind(labels[i]).Unbind()
 	}
 
 	b.ResetTimer()
 
 	for i := 0; i < b.N; i++ {
-		cnt.AcquireHandle(labels[i])
+		cnt.Bind(labels[i])
 	}
 }
 
@@ -179,13 +179,13 @@ func BenchmarkAcquireReleaseExistingHandle(b *testing.B) {
 
 	for i := 0; i < b.N; i++ {
 		labels[i] = fix.sdk.Labels(labelSets[i]...)
-		cnt.AcquireHandle(labels[i]).Release()
+		cnt.Bind(labels[i]).Unbind()
 	}
 
 	b.ResetTimer()
 
 	for i := 0; i < b.N; i++ {
-		cnt.AcquireHandle(labels[i]).Release()
+		cnt.Bind(labels[i]).Unbind()
 	}
 }
 
@@ -209,7 +209,7 @@ func BenchmarkInt64CounterHandleAdd(b *testing.B) {
 	fix := newFixture(b)
 	labs := fix.sdk.Labels(makeLabels(1)...)
 	cnt := fix.sdk.NewInt64Counter("int64.counter")
-	handle := cnt.AcquireHandle(labs)
+	handle := cnt.Bind(labs)
 
 	b.ResetTimer()
 
@@ -236,7 +236,7 @@ func BenchmarkFloat64CounterHandleAdd(b *testing.B) {
 	fix := newFixture(b)
 	labs := fix.sdk.Labels(makeLabels(1)...)
 	cnt := fix.sdk.NewFloat64Counter("float64.counter")
-	handle := cnt.AcquireHandle(labs)
+	handle := cnt.Bind(labs)
 
 	b.ResetTimer()
 
@@ -265,7 +265,7 @@ func BenchmarkInt64GaugeHandleAdd(b *testing.B) {
 	fix := newFixture(b)
 	labs := fix.sdk.Labels(makeLabels(1)...)
 	gau := fix.sdk.NewInt64Gauge("int64.gauge")
-	handle := gau.AcquireHandle(labs)
+	handle := gau.Bind(labs)
 
 	b.ResetTimer()
 
@@ -292,7 +292,7 @@ func BenchmarkFloat64GaugeHandleAdd(b *testing.B) {
 	fix := newFixture(b)
 	labs := fix.sdk.Labels(makeLabels(1)...)
 	gau := fix.sdk.NewFloat64Gauge("float64.gauge")
-	handle := gau.AcquireHandle(labs)
+	handle := gau.Bind(labs)
 
 	b.ResetTimer()
 
@@ -321,7 +321,7 @@ func benchmarkInt64MeasureHandleAdd(b *testing.B, name string) {
 	fix := newFixture(b)
 	labs := fix.sdk.Labels(makeLabels(1)...)
 	mea := fix.sdk.NewInt64Measure(name)
-	handle := mea.AcquireHandle(labs)
+	handle := mea.Bind(labs)
 
 	b.ResetTimer()
 
@@ -348,7 +348,7 @@ func benchmarkFloat64MeasureHandleAdd(b *testing.B, name string) {
 	fix := newFixture(b)
 	labs := fix.sdk.Labels(makeLabels(1)...)
 	mea := fix.sdk.NewFloat64Measure(name)
-	handle := mea.AcquireHandle(labs)
+	handle := mea.Bind(labs)
 
 	b.ResetTimer()
 

sdk/metric/monotone_test.go

@@ -76,7 +76,7 @@ func TestMonotoneGauge(t *testing.T) {
 
 	gauge := sdk.NewInt64Gauge("my.gauge.name", metric.WithMonotonic(true))
 
-	handle := gauge.AcquireHandle(sdk.Labels(key.String("a", "b")))
+	handle := gauge.Bind(sdk.Labels(key.String("a", "b")))
 
 	require.Nil(t, batcher.currentTime)
 	require.Nil(t, batcher.currentValue)

sdk/metric/sdk.go

@@ -148,10 +148,10 @@ type (
 )
 
 var (
-	_ api.Meter          = &SDK{}
-	_ api.LabelSet       = &labels{}
-	_ api.InstrumentImpl = &instrument{}
-	_ api.HandleImpl     = &record{}
+	_ api.Meter               = &SDK{}
+	_ api.LabelSet            = &labels{}
+	_ api.InstrumentImpl      = &instrument{}
+	_ api.BoundInstrumentImpl = &record{}
 
 	// hazardRecord is used as a pointer value that indicates the
 	// value is not included in any list.  (`nil` would be
@@ -205,7 +205,7 @@ func (i *instrument) acquireHandle(ls *labels) *record {
 	return rec
 }
 
-func (i *instrument) AcquireHandle(ls api.LabelSet) api.HandleImpl {
+func (i *instrument) Bind(ls api.LabelSet) api.BoundInstrumentImpl {
 	labs := i.meter.labsFor(ls)
 	return i.acquireHandle(labs)
 }
@@ -213,7 +213,7 @@ func (i *instrument) AcquireHandle(ls api.LabelSet) api.HandleImpl {
 func (i *instrument) RecordOne(ctx context.Context, number core.Number, ls api.LabelSet) {
 	ourLs := i.meter.labsFor(ls)
 	h := i.acquireHandle(ourLs)
-	defer h.Release()
+	defer h.Unbind()
 	h.RecordOne(ctx, number)
 }
 
@@ -465,7 +465,7 @@ func (r *record) RecordOne(ctx context.Context, number core.Number) {
 	}
 }
 
-func (r *record) Release() {
+func (r *record) Unbind() {
 	for {
 		collected := atomic.LoadInt64(&r.collectedEpoch)
 		modified := atomic.LoadInt64(&r.modifiedEpoch)