0doc.go 4.8 KB

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