Skip to content

Commit

Permalink
shorter doc comments for fully-deprecated (ignored) fields/methods (#397
Browse files Browse the repository at this point in the history
)
  • Loading branch information
extemporalgenome authored Nov 28, 2023
1 parent f7f63a0 commit 126da48
Show file tree
Hide file tree
Showing 3 changed files with 6 additions and 29 deletions.
9 changes: 2 additions & 7 deletions codec/decode.go
Original file line number Diff line number Diff line change
Expand Up @@ -1580,14 +1580,9 @@ func (d *Decoder) MustDecode(v interface{}) {
d.calls--
}

// Release releases shared (pooled) resources.
// Release is a no-op.
//
// 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, Release() is automatically called unless the option ExplicitRelease is set.
//
// Deprecated: Release is a no-op as pooled resources are not used with an Decoder.
// Deprecated: Pooled resources are not used with a Decoder.
// This method is kept for compatibility reasons only.
func (d *Decoder) Release() {
}
Expand Down
7 changes: 2 additions & 5 deletions codec/encode.go
Original file line number Diff line number Diff line change
Expand Up @@ -1150,12 +1150,9 @@ func (e *Encoder) MustEncode(v interface{}) {
}
}

// Release releases shared (pooled) resources.
// Release is a no-op.
//
// It is important to call Release() when done with an Encoder, so those resources
// are released instantly for use by subsequently created Encoders.
//
// Deprecated: Release is a no-op as pooled resources are not used with an Encoder.
// Deprecated: Pooled resources are not used with an Encoder.
// This method is kept for compatibility reasons only.
func (e *Encoder) Release() {
}
Expand Down
19 changes: 2 additions & 17 deletions codec/helper.go
Original file line number Diff line number Diff line change
Expand Up @@ -857,26 +857,11 @@ type BasicHandle struct {
// Once a Handle has been initialized (used), do not modify this option. It will be ignored.
TimeNotBuiltin bool

// 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 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 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).Release)
// runtime.SetFinalizer(d, (*Decoder).Release)
// ExplicitRelease is ignored and has no effect.
//
// Deprecated: This is not longer used as pools are only used for long-lived objects
// which are shared across goroutines.
// Setting this value has no effect. It is maintained for backward compatibility.
// It is maintained for backward compatibility.
ExplicitRelease bool

// ---- cache line
Expand Down

0 comments on commit 126da48

Please sign in to comment.