[GitHub] [beam] gonzojive opened a new issue, #21930: [Feature Request]: Go SDK: coder.RegisterCoder needs more precise docstring

[GitBox <gi...@apache.org>]

gonzojive opened a new issue, #21930:
URL: https://github.com/apache/beam/issues/21930

   ### What would you like to happen?
   
   [coder.RegisterCoder](https://pkg.go.dev/github.com/apache/beam/sdks/v2/go/pkg/beam/core/graph/coder#RegisterCoder) should specify the accepted forms of the "enc" and "dec" arguments. Same for `NewCustomCoder`.
   
   ```go
   // RegisterCoder registers a user defined coder for a given type, and will
   // be used if there is no beam coder for that type. Must be called prior to beam.Init(),
   // preferably in an init() function.
   //
   // Coders are encoder and decoder pairs, and operate around []bytes.
   //
   // The coder used for a given type follows this ordering:
   //   1. Coders for Known Beam types.
   //   2. Coders registered for specific types
   //   3. Coders registered for interfaces types
   //   4. Default coder (JSON)
   //
   // Types of kind Interface, are handled specially by the registry, so they may be iterated
   // over to check if element types implement them.
   //
   // Repeated registrations of the same type overrides prior ones.
   ```
   
   ```go
   // NewCustomCoder creates a coder for the supplied parameters defining a
   // particular encoding strategy.
   ```
   
   The implementation seems to rely on this code:
   
   ```go
   func validateEncoder(t reflect.Type, encode interface{}) error {
   	// Check if it uses the real type in question.
   	if err := funcx.Satisfy(encode, funcx.Replace(encodeSig, typex.TType, t)); err != nil {
   		return errors.WithContext(err, "validateEncoder: validating signature")
   	}
   	// TODO(lostluck): 2019.02.03 - Determine if there are encode allocation bottlenecks.
   	return nil
   }
   
   func validateDecoder(t reflect.Type, decode interface{}) error {
   	// Check if it uses the real type in question.
   	if err := funcx.Satisfy(decode, funcx.Replace(decodeSig, typex.TType, t)); err != nil {
   		return errors.WithContext(err, "validateDecoder: validating signature")
   	}
   	// TODO(lostluck): 2019.02.03 - Expand cases to avoid []byte -> interface{} conversion
   	// in exec, & a beam Decoder interface.
   	return nil
   }
   ```
   
   ### Issue Priority
   
   Priority: 2
   
   ### Issue Component
   
   Component: sdk-go


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: github-unsubscribe@beam.apache.org.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

[GitHub] [beam] gonzojive commented on issue #21930: [Feature Request]: Go SDK: coder.RegisterCoder needs more precise docstring

[GitBox <gi...@apache.org>]

gonzojive commented on issue #21930:
URL: https://github.com/apache/beam/issues/21930#issuecomment-1159133353

   Aha, here is what I'm now seeing in the docs. This should at least be linked from the mentioned functions.
   
   ```go
   type CustomCoder struct {
   	// Name is the coder name. Informational only.
   	Name [string](https://pkg.go.dev/builtin#string)
   	// Type is the underlying concrete type that is being coded. It is
   	// available to Enc and Dec. It must be a concrete type.
   	Type [reflect](https://pkg.go.dev/reflect).[Type](https://pkg.go.dev/reflect#Type)
   
   	// Enc is the encoding function : T -> []byte. It may optionally take a
   	// reflect.Type parameter and return an error as well.
   	Enc *[funcx](https://pkg.go.dev/github.com/apache/beam/sdks/v2@v2.39.0/go/pkg/beam/core/funcx).[Fn](https://pkg.go.dev/github.com/apache/beam/sdks/v2@v2.39.0/go/pkg/beam/core/funcx#Fn)
   	// Dec is the decoding function: []byte -> T. It may optionally take a
   	// reflect.Type parameter and return an error as well.
   	Dec *[funcx](https://pkg.go.dev/github.com/apache/beam/sdks/v2@v2.39.0/go/pkg/beam/core/funcx).[Fn](https://pkg.go.dev/github.com/apache/beam/sdks/v2@v2.39.0/go/pkg/beam/core/funcx#Fn)
   
   	ID [string](https://pkg.go.dev/builtin#string) // (optional) This coder's ID if translated from a pipeline proto.
   }
   ```


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: github-unsubscribe@beam.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

[GitHub] [beam] lostluck commented on issue #21930: [Task]: Go SDK: coder.RegisterCoder needs more precise docstring

[GitBox <gi...@apache.org>]

lostluck commented on issue #21930:
URL: https://github.com/apache/beam/issues/21930#issuecomment-1159137913

   Made it a task instead of a new feature, as it's updating the documentation.
   
   My main regret from that API is not making it a factory function. As it stands they need to be pure functions, or global state that needs to be made threadsafe. There's no other option.
   
   Specifically, it's not possible to have "per coder" state, it's either no state or global, which means users have to ensure any state is thread safe, unlike everything else which allows bundle scoped state, which avoids the need for thread safety since an instance is only used by a single bundle at a time.
   


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: github-unsubscribe@beam.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org