codec: refactor: rename (En|De)coder.Close() -> Release(), and option DoNotClose -> ExplicitRelease

codec/decode.go

@@ -2398,7 +2398,7 @@ type Decoder struct {
 
 	// Extensions can call Decode() within a current Decode() call.
 	// We need to know when the top level Decode() call returns,
-	// so we can decide whether to Close() or not.
+	// so we can decide whether to Release() or not.
 	calls uint16 // what depth in mustDecode are we in now.
 
 	_ [2]uint8 // padding
@@ -2630,8 +2630,8 @@ func (d *Decoder) mustDecode(v interface{}) {
 	}
 	// xprintf(">>>>>>>> >>>>>>>> num decFns: %v\n", d.cf.sn)
 	d.calls--
-	if !d.h.DoNotClose && d.calls == 0 {
-		d.Close()
+	if !d.h.ExplicitRelease && d.calls == 0 {
+		d.Release()
 	}
 }
 
@@ -2647,17 +2647,17 @@ func (d *Decoder) mustDecode(v interface{}) {
 //go:noinline -- as it is run by finalizer
 func (d *Decoder) finalize() {
 	// xdebugf("finalizing Decoder")
-	d.Close()
+	d.Release()
 }
 
-// Close releases shared (pooled) resources.
+// Release releases shared (pooled) resources.
 //
-// It is important to call Close() when done with a Decoder, so those resources
+// It is important to call Release() when done with a Decoder, so those resources
 // are released instantly for use by subsequently created Decoders.
 //
-// By default, Close() is automatically called unless the option DoNotClose is set.
-func (d *Decoder) Close() {
-	if useFinalizers && removeFinalizerOnClose {
+// By default, Release() is automatically called unless the option ExplicitRelease is set.
+func (d *Decoder) Release() {
+	if useFinalizers && removeFinalizerOnRelease {
 		runtime.SetFinalizer(d, nil)
 	}
 	if d.bi != nil && d.bi.bytesBufPooler.pool != nil {

codec/encode.go

@@ -1260,7 +1260,7 @@ type Encoder struct {
 
 	// Extensions can call Encode() within a current Encode() call.
 	// We need to know when the top level Encode() call returns,
-	// so we can decide whether to Close() or not.
+	// so we can decide whether to Release() or not.
 	calls uint16 // what depth in mustEncode are we in now.
 
 	b [(5 * 8) - 2]byte // for encoding chan or (non-addressable) [N]byte
@@ -1499,8 +1499,8 @@ func (e *Encoder) mustEncode(v interface{}) {
 	e.e.atEndOfEncode()
 	e.w.end()
 	e.calls--
-	if !e.h.DoNotClose && e.calls == 0 {
-		e.Close()
+	if !e.h.ExplicitRelease && e.calls == 0 {
+		e.Release()
 	}
 }
 
@@ -1516,16 +1516,16 @@ func (e *Encoder) mustEncode(v interface{}) {
 
 //go:noinline -- as it is run by finalizer
 func (e *Encoder) finalize() {
-	xdebugf("finalizing Encoder")
-	e.Close()
+	// xdebugf("finalizing Encoder")
+	e.Release()
 }
 
-// Close releases shared (pooled) resources.
+// Release releases shared (pooled) resources.
 //
-// It is important to call Close() when done with an Encoder, so those resources
+// It is important to call Release() when done with an Encoder, so those resources
 // are released instantly for use by subsequently created Encoders.
-func (e *Encoder) Close() {
-	if useFinalizers && removeFinalizerOnClose {
+func (e *Encoder) Release() {
+	if useFinalizers && removeFinalizerOnRelease {
 		runtime.SetFinalizer(e, nil)
 	}
 	if e.wf != nil {

codec/helper.go

@@ -139,18 +139,18 @@ const (
 	// so structFieldInfo fits into 8 bytes
 	maxLevelsEmbedding = 14
 
-	// finalizers are used? to Close Encoder/Decoder when they are GC'ed
-	// so that their pooled resources are returned.
+	// useFinalizers=true configures finalizers to release pool'ed resources
+	// acquired by Encoder/Decoder during their GC.
 	//
 	// Note that calling SetFinalizer is always expensive,
 	// as code must be run on the systemstack even for SetFinalizer(t, nil).
 	//
-	// We document that folks SHOULD call Close() when done, or they can
+	// We document that folks SHOULD call Release() when done, or they can
 	// explicitly call SetFinalizer themselves e.g.
-	//    runtime.SetFinalizer(e, (*Encoder).Close)
-	//    runtime.SetFinalizer(d, (*Decoder).Close)
-	useFinalizers          = false
-	removeFinalizerOnClose = false
+	//    runtime.SetFinalizer(e, (*Encoder).Release)
+	//    runtime.SetFinalizer(d, (*Decoder).Release)
+	useFinalizers            = false
+	removeFinalizerOnRelease = false
 )
 
 var oneByteArr [1]byte
@@ -542,22 +542,23 @@ type BasicHandle struct {
 	// (for Cbor and Msgpack), where time.Time was not a builtin supported type.
 	TimeNotBuiltin bool
 
-	// DoNotClose configures whether Close() is implicitly called after an encode or
+	// ExplicitRelease configures whether Release() is implicitly called after an encode or
 	// decode call.
 	//
 	// If you will hold onto an Encoder or Decoder for re-use, by calling Reset(...)
-	// on it, then you do not want it to be implicitly closed after each Encode/Decode call.
+	// on it or calling (Must)Encode repeatedly into a given []byte or io.Writer,
+	// then you do not want it to be implicitly closed after each Encode/Decode call.
 	// Doing so will unnecessarily return resources to the shared pool, only for you to
 	// grab them right after again to do another Encode/Decode call.
 	//
-	// Instead, you configure DoNotClose=true, and you explicitly call Close() when
+	// Instead, you configure ExplicitRelease=true, and you explicitly call Release() when
 	// you are truly done.
 	//
 	// As an alternative, you can explicitly set a finalizer - so its resources
 	// are returned to the shared pool before it is garbage-collected. Do it as below:
-	//    runtime.SetFinalizer(e, (*Encoder).Close)
-	//    runtime.SetFinalizer(d, (*Decoder).Close)
-	DoNotClose bool
+	//    runtime.SetFinalizer(e, (*Encoder).Release)
+	//    runtime.SetFinalizer(d, (*Decoder).Release)
+	ExplicitRelease bool
 
 	be bool   // is handle a binary encoding?
 	js bool   // is handle javascript handler?

codec/shared_test.go

@@ -140,12 +140,12 @@ func init() {
 	testHandles = append(testHandles,
 		// testNoopH,
 		testMsgpackH, testBincH, testSimpleH, testCborH, testJsonH)
-	// set DoNotClose on each handle
-	testMsgpackH.DoNotClose = true
-	testBincH.DoNotClose = true
-	testSimpleH.DoNotClose = true
-	testCborH.DoNotClose = true
-	testJsonH.DoNotClose = true
+	// set ExplicitRelease on each handle
+	testMsgpackH.ExplicitRelease = true
+	testBincH.ExplicitRelease = true
+	testSimpleH.ExplicitRelease = true
+	testCborH.ExplicitRelease = true
+	testJsonH.ExplicitRelease = true
 
 	testInitFlags()
 	benchInitFlags()
@@ -242,7 +242,7 @@ func sTestCodecEncode(ts interface{}, bsIn []byte, fn func([]byte) *bytes.Buffer
 		bh.WriterBufferSize = oldWriteBufferSize
 	}
 	if !testUseReset {
-		e.Close()
+		e.Release()
 	}
 	return
 }
@@ -277,7 +277,7 @@ func sTestCodecDecode(bs []byte, ts interface{}, h Handle, bh *BasicHandle) (err
 		bh.ReaderBufferSize = oldReadBufferSize
 	}
 	if !testUseReset {
-		d.Close()
+		d.Release()
 	}
 	return
 }