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,26 +181,26 @@ 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,
 		labels: labels,
 	}
 }
 
-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,20 +40,20 @@ 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)
 }
 
 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"