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