"Fossies" - the Fresh Open Source Software Archive

Member "vault-1.3.0/vendor/github.com/ugorji/go/codec/0doc.go" (12 Nov 2019, 8939 Bytes) of package /linux/misc/vault-1.3.0.tar.gz:


As a special service "Fossies" has tried to format the requested source page into HTML format using (guessed) Go source code syntax highlighting (style: standard) with prefixed line numbers and code folding option. Alternatively you can here view or download the uninterpreted source code file. See also the last Fossies "Diffs" side-by-side code changes report for "0doc.go": 1.1.4_vs_1.2.0.

    1 // Copyright (c) 2012-2018 Ugorji Nwoke. All rights reserved.
    2 // Use of this source code is governed by a MIT license found in the LICENSE file.
    3 
    4 /*
    5 Package codec provides a
    6 High Performance, Feature-Rich Idiomatic Go 1.4+ codec/encoding library
    7 for binc, msgpack, cbor, json.
    8 
    9 Supported Serialization formats are:
   10 
   11   - msgpack: https://github.com/msgpack/msgpack
   12   - binc:    http://github.com/ugorji/binc
   13   - cbor:    http://cbor.io http://tools.ietf.org/html/rfc7049
   14   - json:    http://json.org http://tools.ietf.org/html/rfc7159
   15   - simple:
   16 
   17 To install:
   18 
   19     go get github.com/ugorji/go/codec
   20 
   21 This package will carefully use 'unsafe' for performance reasons in specific places.
   22 You can build without unsafe use by passing the safe or appengine tag
   23 i.e. 'go install -tags=safe ...'. Note that unsafe is only supported for the last 3
   24 go sdk versions e.g. current go release is go 1.9, so we support unsafe use only from
   25 go 1.7+ . This is because supporting unsafe requires knowledge of implementation details.
   26 
   27 For detailed usage information, read the primer at http://ugorji.net/blog/go-codec-primer .
   28 
   29 The idiomatic Go support is as seen in other encoding packages in
   30 the standard library (ie json, xml, gob, etc).
   31 
   32 Rich Feature Set includes:
   33 
   34   - Simple but extremely powerful and feature-rich API
   35   - Support for go1.4 and above, while selectively using newer APIs for later releases
   36   - Excellent code coverage ( > 90% )
   37   - Very High Performance.
   38     Our extensive benchmarks show us outperforming Gob, Json, Bson, etc by 2-4X.
   39   - Careful selected use of 'unsafe' for targeted performance gains.
   40     100% mode exists where 'unsafe' is not used at all.
   41   - Lock-free (sans mutex) concurrency for scaling to 100's of cores
   42   - In-place updates during decode, with option to zero value in maps and slices prior to decode
   43   - Coerce types where appropriate
   44     e.g. decode an int in the stream into a float, decode numbers from formatted strings, etc
   45   - Corner Cases:
   46     Overflows, nil maps/slices, nil values in streams are handled correctly
   47   - Standard field renaming via tags
   48   - Support for omitting empty fields during an encoding
   49   - Encoding from any value and decoding into pointer to any value
   50     (struct, slice, map, primitives, pointers, interface{}, etc)
   51   - Extensions to support efficient encoding/decoding of any named types
   52   - Support encoding.(Binary|Text)(M|Unm)arshaler interfaces
   53   - Support IsZero() bool to determine if a value is a zero value.
   54     Analogous to time.Time.IsZero() bool.
   55   - Decoding without a schema (into a interface{}).
   56     Includes Options to configure what specific map or slice type to use
   57     when decoding an encoded list or map into a nil interface{}
   58   - Mapping a non-interface type to an interface, so we can decode appropriately
   59     into any interface type with a correctly configured non-interface value.
   60   - Encode a struct as an array, and decode struct from an array in the data stream
   61   - Option to encode struct keys as numbers (instead of strings)
   62     (to support structured streams with fields encoded as numeric codes)
   63   - Comprehensive support for anonymous fields
   64   - Fast (no-reflection) encoding/decoding of common maps and slices
   65   - Code-generation for faster performance.
   66   - Support binary (e.g. messagepack, cbor) and text (e.g. json) formats
   67   - Support indefinite-length formats to enable true streaming
   68     (for formats which support it e.g. json, cbor)
   69   - Support canonical encoding, where a value is ALWAYS encoded as same sequence of bytes.
   70     This mostly applies to maps, where iteration order is non-deterministic.
   71   - NIL in data stream decoded as zero value
   72   - Never silently skip data when decoding.
   73     User decides whether to return an error or silently skip data when keys or indexes
   74     in the data stream do not map to fields in the struct.
   75   - Detect and error when encoding a cyclic reference (instead of stack overflow shutdown)
   76   - Encode/Decode from/to chan types (for iterative streaming support)
   77   - Drop-in replacement for encoding/json. `json:` key in struct tag supported.
   78   - Provides a RPC Server and Client Codec for net/rpc communication protocol.
   79   - Handle unique idiosyncrasies of codecs e.g.
   80     - For messagepack, configure how ambiguities in handling raw bytes are resolved
   81     - For messagepack, provide rpc server/client codec to support
   82       msgpack-rpc protocol defined at:
   83       https://github.com/msgpack-rpc/msgpack-rpc/blob/master/spec.md
   84 
   85 Extension Support
   86 
   87 Users can register a function to handle the encoding or decoding of
   88 their custom types.
   89 
   90 There are no restrictions on what the custom type can be. Some examples:
   91 
   92     type BisSet   []int
   93     type BitSet64 uint64
   94     type UUID     string
   95     type MyStructWithUnexportedFields struct { a int; b bool; c []int; }
   96     type GifImage struct { ... }
   97 
   98 As an illustration, MyStructWithUnexportedFields would normally be
   99 encoded as an empty map because it has no exported fields, while UUID
  100 would be encoded as a string. However, with extension support, you can
  101 encode any of these however you like.
  102 
  103 Custom Encoding and Decoding
  104 
  105 This package maintains symmetry in the encoding and decoding halfs.
  106 We determine how to encode or decode by walking this decision tree
  107 
  108   - is type a codec.Selfer?
  109   - is there an extension registered for the type?
  110   - is format binary, and is type a encoding.BinaryMarshaler and BinaryUnmarshaler?
  111   - is format specifically json, and is type a encoding/json.Marshaler and Unmarshaler?
  112   - is format text-based, and type an encoding.TextMarshaler?
  113   - else we use a pair of functions based on the "kind" of the type e.g. map, slice, int64, etc
  114 
  115 This symmetry is important to reduce chances of issues happening because the
  116 encoding and decoding sides are out of sync e.g. decoded via very specific
  117 encoding.TextUnmarshaler but encoded via kind-specific generalized mode.
  118 
  119 Consequently, if a type only defines one-half of the symmetry
  120 (e.g. it implements UnmarshalJSON() but not MarshalJSON() ),
  121 then that type doesn't satisfy the check and we will continue walking down the
  122 decision tree.
  123 
  124 RPC
  125 
  126 RPC Client and Server Codecs are implemented, so the codecs can be used
  127 with the standard net/rpc package.
  128 
  129 Usage
  130 
  131 The Handle is SAFE for concurrent READ, but NOT SAFE for concurrent modification.
  132 
  133 The Encoder and Decoder are NOT safe for concurrent use.
  134 
  135 Consequently, the usage model is basically:
  136 
  137     - Create and initialize the Handle before any use.
  138       Once created, DO NOT modify it.
  139     - Multiple Encoders or Decoders can now use the Handle concurrently.
  140       They only read information off the Handle (never write).
  141     - However, each Encoder or Decoder MUST not be used concurrently
  142     - To re-use an Encoder/Decoder, call Reset(...) on it first.
  143       This allows you use state maintained on the Encoder/Decoder.
  144 
  145 Sample usage model:
  146 
  147     // create and configure Handle
  148     var (
  149       bh codec.BincHandle
  150       mh codec.MsgpackHandle
  151       ch codec.CborHandle
  152     )
  153 
  154     mh.MapType = reflect.TypeOf(map[string]interface{}(nil))
  155 
  156     // configure extensions
  157     // e.g. for msgpack, define functions and enable Time support for tag 1
  158     // mh.SetExt(reflect.TypeOf(time.Time{}), 1, myExt)
  159 
  160     // create and use decoder/encoder
  161     var (
  162       r io.Reader
  163       w io.Writer
  164       b []byte
  165       h = &bh // or mh to use msgpack
  166     )
  167 
  168     dec = codec.NewDecoder(r, h)
  169     dec = codec.NewDecoderBytes(b, h)
  170     err = dec.Decode(&v)
  171 
  172     enc = codec.NewEncoder(w, h)
  173     enc = codec.NewEncoderBytes(&b, h)
  174     err = enc.Encode(v)
  175 
  176     //RPC Server
  177     go func() {
  178         for {
  179             conn, err := listener.Accept()
  180             rpcCodec := codec.GoRpc.ServerCodec(conn, h)
  181             //OR rpcCodec := codec.MsgpackSpecRpc.ServerCodec(conn, h)
  182             rpc.ServeCodec(rpcCodec)
  183         }
  184     }()
  185 
  186     //RPC Communication (client side)
  187     conn, err = net.Dial("tcp", "localhost:5555")
  188     rpcCodec := codec.GoRpc.ClientCodec(conn, h)
  189     //OR rpcCodec := codec.MsgpackSpecRpc.ClientCodec(conn, h)
  190     client := rpc.NewClientWithCodec(rpcCodec)
  191 
  192 Running Tests
  193 
  194 To run tests, use the following:
  195 
  196     go test
  197 
  198 To run the full suite of tests, use the following:
  199 
  200     go test -tags alltests -run Suite
  201 
  202 You can run the tag 'safe' to run tests or build in safe mode. e.g.
  203 
  204     go test -tags safe -run Json
  205     go test -tags "alltests safe" -run Suite
  206 
  207 Running Benchmarks
  208 
  209 Please see http://github.com/ugorji/go-codec-bench .
  210 
  211 Caveats
  212 
  213 Struct fields matching the following are ignored during encoding and decoding
  214     - struct tag value set to -
  215     - func, complex numbers, unsafe pointers
  216     - unexported and not embedded
  217     - unexported and embedded and not struct kind
  218     - unexported and embedded pointers (from go1.10)
  219 
  220 Every other field in a struct will be encoded/decoded.
  221 
  222 Embedded fields are encoded as if they exist in the top-level struct,
  223 with some caveats. See Encode documentation.
  224 
  225 */
  226 package codec
  227