1// Copyright (c) 2012, 2013 Ugorji Nwoke. All rights reserved. 2// Use of this source code is governed by a BSD-style license found in the LICENSE file. 3 4/* 5High Performance, Feature-Rich Idiomatic Go encoding library for msgpack and binc . 6 7Supported Serialization formats are: 8 9 - msgpack: [https://github.com/msgpack/msgpack] 10 - binc: [http://github.com/ugorji/binc] 11 12To install: 13 14 go get github.com/ugorji/go/codec 15 16The idiomatic Go support is as seen in other encoding packages in 17the standard library (ie json, xml, gob, etc). 18 19Rich Feature Set includes: 20 21 - Simple but extremely powerful and feature-rich API 22 - Very High Performance. 23 Our extensive benchmarks show us outperforming Gob, Json and Bson by 2-4X. 24 This was achieved by taking extreme care on: 25 - managing allocation 26 - function frame size (important due to Go's use of split stacks), 27 - reflection use (and by-passing reflection for common types) 28 - recursion implications 29 - zero-copy mode (encoding/decoding to byte slice without using temp buffers) 30 - Correct. 31 Care was taken to precisely handle corner cases like: 32 overflows, nil maps and slices, nil value in stream, etc. 33 - Efficient zero-copying into temporary byte buffers 34 when encoding into or decoding from a byte slice. 35 - Standard field renaming via tags 36 - Encoding from any value 37 (struct, slice, map, primitives, pointers, interface{}, etc) 38 - Decoding into pointer to any non-nil typed value 39 (struct, slice, map, int, float32, bool, string, reflect.Value, etc) 40 - Supports extension functions to handle the encode/decode of custom types 41 - Support Go 1.2 encoding.BinaryMarshaler/BinaryUnmarshaler 42 - Schema-less decoding 43 (decode into a pointer to a nil interface{} as opposed to a typed non-nil value). 44 Includes Options to configure what specific map or slice type to use 45 when decoding an encoded list or map into a nil interface{} 46 - Provides a RPC Server and Client Codec for net/rpc communication protocol. 47 - Msgpack Specific: 48 - Provides extension functions to handle spec-defined extensions (binary, timestamp) 49 - Options to resolve ambiguities in handling raw bytes (as string or []byte) 50 during schema-less decoding (decoding into a nil interface{}) 51 - RPC Server/Client Codec for msgpack-rpc protocol defined at: 52 https://github.com/msgpack-rpc/msgpack-rpc/blob/master/spec.md 53 - Fast Paths for some container types: 54 For some container types, we circumvent reflection and its associated overhead 55 and allocation costs, and encode/decode directly. These types are: 56 []interface{} 57 []int 58 []string 59 map[interface{}]interface{} 60 map[int]interface{} 61 map[string]interface{} 62 63Extension Support 64 65Users can register a function to handle the encoding or decoding of 66their custom types. 67 68There are no restrictions on what the custom type can be. Some examples: 69 70 type BisSet []int 71 type BitSet64 uint64 72 type UUID string 73 type MyStructWithUnexportedFields struct { a int; b bool; c []int; } 74 type GifImage struct { ... } 75 76As an illustration, MyStructWithUnexportedFields would normally be 77encoded as an empty map because it has no exported fields, while UUID 78would be encoded as a string. However, with extension support, you can 79encode any of these however you like. 80 81RPC 82 83RPC Client and Server Codecs are implemented, so the codecs can be used 84with the standard net/rpc package. 85 86Usage 87 88Typical usage model: 89 90 // create and configure Handle 91 var ( 92 bh codec.BincHandle 93 mh codec.MsgpackHandle 94 ) 95 96 mh.MapType = reflect.TypeOf(map[string]interface{}(nil)) 97 98 // configure extensions 99 // e.g. for msgpack, define functions and enable Time support for tag 1 100 // mh.AddExt(reflect.TypeOf(time.Time{}), 1, myMsgpackTimeEncodeExtFn, myMsgpackTimeDecodeExtFn) 101 102 // create and use decoder/encoder 103 var ( 104 r io.Reader 105 w io.Writer 106 b []byte 107 h = &bh // or mh to use msgpack 108 ) 109 110 dec = codec.NewDecoder(r, h) 111 dec = codec.NewDecoderBytes(b, h) 112 err = dec.Decode(&v) 113 114 enc = codec.NewEncoder(w, h) 115 enc = codec.NewEncoderBytes(&b, h) 116 err = enc.Encode(v) 117 118 //RPC Server 119 go func() { 120 for { 121 conn, err := listener.Accept() 122 rpcCodec := codec.GoRpc.ServerCodec(conn, h) 123 //OR rpcCodec := codec.MsgpackSpecRpc.ServerCodec(conn, h) 124 rpc.ServeCodec(rpcCodec) 125 } 126 }() 127 128 //RPC Communication (client side) 129 conn, err = net.Dial("tcp", "localhost:5555") 130 rpcCodec := codec.GoRpc.ClientCodec(conn, h) 131 //OR rpcCodec := codec.MsgpackSpecRpc.ClientCodec(conn, h) 132 client := rpc.NewClientWithCodec(rpcCodec) 133 134Representative Benchmark Results 135 136Run the benchmark suite using: 137 go test -bi -bench=. -benchmem 138 139To run full benchmark suite (including against vmsgpack and bson), 140see notes in ext_dep_test.go 141 142*/ 143package codec 144