diff options
Diffstat (limited to 'vendor/github.com/ugorji/go/codec/doc.go')
| -rw-r--r-- | vendor/github.com/ugorji/go/codec/doc.go | 157 |
1 files changed, 78 insertions, 79 deletions
diff --git a/vendor/github.com/ugorji/go/codec/doc.go b/vendor/github.com/ugorji/go/codec/doc.go index b390f9a8f..1a16bca8b 100644 --- a/vendor/github.com/ugorji/go/codec/doc.go +++ b/vendor/github.com/ugorji/go/codec/doc.go @@ -73,23 +73,23 @@ Rich Feature Set includes: - Drop-in replacement for encoding/json. `json:` key in struct tag supported. - Provides a RPC Server and Client Codec for net/rpc communication protocol. - Handle unique idiosyncrasies of codecs e.g. - - For messagepack, configure how ambiguities in handling raw bytes are resolved - - For messagepack, provide rpc server/client codec to support - msgpack-rpc protocol defined at: - https://github.com/msgpack-rpc/msgpack-rpc/blob/master/spec.md + For messagepack, configure how ambiguities in handling raw bytes are resolved and + provide rpc server/client codec to support + msgpack-rpc protocol defined at: + https://github.com/msgpack-rpc/msgpack-rpc/blob/master/spec.md -Extension Support +# Extension Support Users can register a function to handle the encoding or decoding of their custom types. There are no restrictions on what the custom type can be. Some examples: - type BisSet []int - type BitSet64 uint64 - type UUID string - type MyStructWithUnexportedFields struct { a int; b bool; c []int; } - type GifImage struct { ... } + type BisSet []int + type BitSet64 uint64 + type UUID string + type MyStructWithUnexportedFields struct { a int; b bool; c []int; } + type GifImage struct { ... } As an illustration, MyStructWithUnexportedFields would normally be encoded as an empty map because it has no exported fields, while UUID @@ -99,7 +99,7 @@ encode any of these however you like. There is also seamless support provided for registering an extension (with a tag) but letting the encoding mechanism default to the standard way. -Custom Encoding and Decoding +# Custom Encoding and Decoding This package maintains symmetry in the encoding and decoding halfs. We determine how to encode or decode by walking this decision tree @@ -120,12 +120,12 @@ Consequently, if a type only defines one-half of the symmetry then that type doesn't satisfy the check and we will continue walking down the decision tree. -RPC +# RPC RPC Client and Server Codecs are implemented, so the codecs can be used with the standard net/rpc package. -Usage +# Usage The Handle is SAFE for concurrent READ, but NOT SAFE for concurrent modification. @@ -133,96 +133,95 @@ The Encoder and Decoder are NOT safe for concurrent use. Consequently, the usage model is basically: - - Create and initialize the Handle before any use. - Once created, DO NOT modify it. - - Multiple Encoders or Decoders can now use the Handle concurrently. - They only read information off the Handle (never write). - - However, each Encoder or Decoder MUST not be used concurrently - - To re-use an Encoder/Decoder, call Reset(...) on it first. - This allows you use state maintained on the Encoder/Decoder. + - Create and initialize the Handle before any use. + Once created, DO NOT modify it. + - Multiple Encoders or Decoders can now use the Handle concurrently. + They only read information off the Handle (never write). + - However, each Encoder or Decoder MUST not be used concurrently + - To re-use an Encoder/Decoder, call Reset(...) on it first. + This allows you use state maintained on the Encoder/Decoder. Sample usage model: - // create and configure Handle - var ( - bh codec.BincHandle - mh codec.MsgpackHandle - ch codec.CborHandle - ) - - mh.MapType = reflect.TypeOf(map[string]interface{}(nil)) - - // configure extensions - // e.g. for msgpack, define functions and enable Time support for tag 1 - // mh.SetExt(reflect.TypeOf(time.Time{}), 1, myExt) - - // create and use decoder/encoder - var ( - r io.Reader - w io.Writer - b []byte - h = &bh // or mh to use msgpack - ) - - dec = codec.NewDecoder(r, h) - dec = codec.NewDecoderBytes(b, h) - err = dec.Decode(&v) - - enc = codec.NewEncoder(w, h) - enc = codec.NewEncoderBytes(&b, h) - err = enc.Encode(v) - - //RPC Server - go func() { - for { - conn, err := listener.Accept() - rpcCodec := codec.GoRpc.ServerCodec(conn, h) - //OR rpcCodec := codec.MsgpackSpecRpc.ServerCodec(conn, h) - rpc.ServeCodec(rpcCodec) - } - }() - - //RPC Communication (client side) - conn, err = net.Dial("tcp", "localhost:5555") - rpcCodec := codec.GoRpc.ClientCodec(conn, h) - //OR rpcCodec := codec.MsgpackSpecRpc.ClientCodec(conn, h) - client := rpc.NewClientWithCodec(rpcCodec) - -Running Tests + // create and configure Handle + var ( + bh codec.BincHandle + mh codec.MsgpackHandle + ch codec.CborHandle + ) + + mh.MapType = reflect.TypeOf(map[string]interface{}(nil)) + + // configure extensions + // e.g. for msgpack, define functions and enable Time support for tag 1 + // mh.SetExt(reflect.TypeOf(time.Time{}), 1, myExt) + + // create and use decoder/encoder + var ( + r io.Reader + w io.Writer + b []byte + h = &bh // or mh to use msgpack + ) + + dec = codec.NewDecoder(r, h) + dec = codec.NewDecoderBytes(b, h) + err = dec.Decode(&v) + + enc = codec.NewEncoder(w, h) + enc = codec.NewEncoderBytes(&b, h) + err = enc.Encode(v) + + //RPC Server + go func() { + for { + conn, err := listener.Accept() + rpcCodec := codec.GoRpc.ServerCodec(conn, h) + //OR rpcCodec := codec.MsgpackSpecRpc.ServerCodec(conn, h) + rpc.ServeCodec(rpcCodec) + } + }() + + //RPC Communication (client side) + conn, err = net.Dial("tcp", "localhost:5555") + rpcCodec := codec.GoRpc.ClientCodec(conn, h) + //OR rpcCodec := codec.MsgpackSpecRpc.ClientCodec(conn, h) + client := rpc.NewClientWithCodec(rpcCodec) + +# Running Tests To run tests, use the following: - go test + go test To run the full suite of tests, use the following: - go test -tags alltests -run Suite + go test -tags alltests -run Suite You can run the tag 'codec.safe' to run tests or build in safe mode. e.g. - go test -tags codec.safe -run Json - go test -tags "alltests codec.safe" -run Suite + go test -tags codec.safe -run Json + go test -tags "alltests codec.safe" -run Suite Running Benchmarks - cd bench - go test -bench . -benchmem -benchtime 1s + cd bench + go test -bench . -benchmem -benchtime 1s Please see http://github.com/ugorji/go-codec-bench . -Caveats +# Caveats Struct fields matching the following are ignored during encoding and decoding - - struct tag value set to - - - func, complex numbers, unsafe pointers - - unexported and not embedded - - unexported and embedded and not struct kind - - unexported and embedded pointers (from go1.10) + - struct tag value set to - + - func, complex numbers, unsafe pointers + - unexported and not embedded + - unexported and embedded and not struct kind + - unexported and embedded pointers (from go1.10) Every other field in a struct will be encoded/decoded. Embedded fields are encoded as if they exist in the top-level struct, with some caveats. See Encode documentation. - */ package codec |