123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143 |
- // Copyright (c) 2012, 2013 Ugorji Nwoke. All rights reserved.
- // Use of this source code is governed by a BSD-style license found in the LICENSE file.
- /*
- High Performance, Feature-Rich Idiomatic Go encoding library for msgpack and binc .
- Supported Serialization formats are:
- - msgpack: [https://github.com/msgpack/msgpack]
- - binc: [http://github.com/ugorji/binc]
- To install:
- go get github.com/ugorji/go/codec
- The idiomatic Go support is as seen in other encoding packages in
- the standard library (ie json, xml, gob, etc).
- Rich Feature Set includes:
- - Simple but extremely powerful and feature-rich API
- - Very High Performance.
- Our extensive benchmarks show us outperforming Gob, Json and Bson by 2-4X.
- This was achieved by taking extreme care on:
- - managing allocation
- - function frame size (important due to Go's use of split stacks),
- - reflection use (and by-passing reflection for common types)
- - recursion implications
- - zero-copy mode (encoding/decoding to byte slice without using temp buffers)
- - Correct.
- Care was taken to precisely handle corner cases like:
- overflows, nil maps and slices, nil value in stream, etc.
- - Efficient zero-copying into temporary byte buffers
- when encoding into or decoding from a byte slice.
- - Standard field renaming via tags
- - Encoding from any value
- (struct, slice, map, primitives, pointers, interface{}, etc)
- - Decoding into pointer to any non-nil typed value
- (struct, slice, map, int, float32, bool, string, reflect.Value, etc)
- - Supports extension functions to handle the encode/decode of custom types
- - Support Go 1.2 encoding.BinaryMarshaler/BinaryUnmarshaler
- - Schema-less decoding
- (decode into a pointer to a nil interface{} as opposed to a typed non-nil value).
- Includes Options to configure what specific map or slice type to use
- when decoding an encoded list or map into a nil interface{}
- - Provides a RPC Server and Client Codec for net/rpc communication protocol.
- - Msgpack Specific:
- - Provides extension functions to handle spec-defined extensions (binary, timestamp)
- - Options to resolve ambiguities in handling raw bytes (as string or []byte)
- during schema-less decoding (decoding into a nil interface{})
- - RPC Server/Client Codec for msgpack-rpc protocol defined at:
- https://github.com/msgpack-rpc/msgpack-rpc/blob/master/spec.md
- - Fast Paths for some container types:
- For some container types, we circumvent reflection and its associated overhead
- and allocation costs, and encode/decode directly. These types are:
- []interface{}
- []int
- []string
- map[interface{}]interface{}
- map[int]interface{}
- map[string]interface{}
- 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 { ... }
- As an illustration, MyStructWithUnexportedFields would normally be
- encoded as an empty map because it has no exported fields, while UUID
- would be encoded as a string. However, with extension support, you can
- encode any of these however you like.
- RPC
- RPC Client and Server Codecs are implemented, so the codecs can be used
- with the standard net/rpc package.
- Usage
- Typical usage model:
- // create and configure Handle
- var (
- bh codec.BincHandle
- mh codec.MsgpackHandle
- )
- mh.MapType = reflect.TypeOf(map[string]interface{}(nil))
- // configure extensions
- // e.g. for msgpack, define functions and enable Time support for tag 1
- // mh.AddExt(reflect.TypeOf(time.Time{}), 1, myMsgpackTimeEncodeExtFn, myMsgpackTimeDecodeExtFn)
- // 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)
- Representative Benchmark Results
- Run the benchmark suite using:
- go test -bi -bench=. -benchmem
- To run full benchmark suite (including against vmsgpack and bson),
- see notes in ext_dep_test.go
- */
- package codec
|