1 // Copyright 2009 The Go Authors. All rights reserved.
2 // Use of this source code is governed by a BSD-style
3 // license that can be found in the LICENSE file.
14 const uint64Size = int(unsafe.Sizeof(uint64(0)))
16 // encoderState is the global execution state of an instance of the encoder.
17 // Field numbers are delta encoded and always increase. The field
18 // number is initialized to -1 so 0 comes out as delta(1). A delta of
19 // 0 terminates the structure.
20 type encoderState struct {
23 sendZero bool // encoding an array element or map key/value pair; send zero values
24 fieldnum int // the last field number written.
25 buf [1 + uint64Size]byte // buffer used by the encoder; here to avoid allocation.
26 next *encoderState // for free list
29 func (enc *Encoder) newEncoderState(b *bytes.Buffer) *encoderState {
43 func (enc *Encoder) freeEncoderState(e *encoderState) {
48 // Unsigned integers have a two-state encoding. If the number is less
49 // than 128 (0 through 0x7F), its value is written directly.
50 // Otherwise the value is written in big-endian byte order preceded
51 // by the byte length, negated.
53 // encodeUint writes an encoded unsigned integer to state.b.
54 func (state *encoderState) encodeUint(x uint64) {
56 err := state.b.WriteByte(uint8(x))
64 state.buf[i] = uint8(x)
68 state.buf[i] = uint8(i - uint64Size) // = loop count, negated
69 _, err := state.b.Write(state.buf[i : uint64Size+1])
75 // encodeInt writes an encoded signed integer to state.w.
76 // The low bit of the encoding says whether to bit complement the (other bits of the)
77 // uint to recover the int.
78 func (state *encoderState) encodeInt(i int64) {
85 state.encodeUint(uint64(x))
88 // encOp is the signature of an encoding operator for a given type.
89 type encOp func(i *encInstr, state *encoderState, p unsafe.Pointer)
91 // The 'instructions' of the encoding machine
92 type encInstr struct {
94 field int // field number
95 indir int // how many pointer indirections to reach the value in the struct
96 offset uintptr // offset in the structure of the field to encode
99 // update emits a field number and updates the state to record its value for delta encoding.
100 // If the instruction pointer is nil, it does nothing
101 func (state *encoderState) update(instr *encInstr) {
103 state.encodeUint(uint64(instr.field - state.fieldnum))
104 state.fieldnum = instr.field
108 // Each encoder for a composite is responsible for handling any
109 // indirections associated with the elements of the data structure.
110 // If any pointer so reached is nil, no bytes are written. If the
111 // data item is zero, no bytes are written. Single values - ints,
112 // strings etc. - are indirected before calling their encoders.
113 // Otherwise, the output (for a scalar) is the field number, as an
114 // encoded integer, followed by the field data in its appropriate
117 // encIndirect dereferences p indir times and returns the result.
118 func encIndirect(p unsafe.Pointer, indir int) unsafe.Pointer {
119 for ; indir > 0; indir-- {
120 p = *(*unsafe.Pointer)(p)
122 return unsafe.Pointer(nil)
128 // encBool encodes the bool with address p as an unsigned 0 or 1.
129 func encBool(i *encInstr, state *encoderState, p unsafe.Pointer) {
131 if b || state.sendZero {
141 // encInt encodes the int with address p.
142 func encInt(i *encInstr, state *encoderState, p unsafe.Pointer) {
143 v := int64(*(*int)(p))
144 if v != 0 || state.sendZero {
150 // encUint encodes the uint with address p.
151 func encUint(i *encInstr, state *encoderState, p unsafe.Pointer) {
152 v := uint64(*(*uint)(p))
153 if v != 0 || state.sendZero {
159 // encInt8 encodes the int8 with address p.
160 func encInt8(i *encInstr, state *encoderState, p unsafe.Pointer) {
161 v := int64(*(*int8)(p))
162 if v != 0 || state.sendZero {
168 // encUint8 encodes the uint8 with address p.
169 func encUint8(i *encInstr, state *encoderState, p unsafe.Pointer) {
170 v := uint64(*(*uint8)(p))
171 if v != 0 || state.sendZero {
177 // encInt16 encodes the int16 with address p.
178 func encInt16(i *encInstr, state *encoderState, p unsafe.Pointer) {
179 v := int64(*(*int16)(p))
180 if v != 0 || state.sendZero {
186 // encUint16 encodes the uint16 with address p.
187 func encUint16(i *encInstr, state *encoderState, p unsafe.Pointer) {
188 v := uint64(*(*uint16)(p))
189 if v != 0 || state.sendZero {
195 // encInt32 encodes the int32 with address p.
196 func encInt32(i *encInstr, state *encoderState, p unsafe.Pointer) {
197 v := int64(*(*int32)(p))
198 if v != 0 || state.sendZero {
204 // encUint encodes the uint32 with address p.
205 func encUint32(i *encInstr, state *encoderState, p unsafe.Pointer) {
206 v := uint64(*(*uint32)(p))
207 if v != 0 || state.sendZero {
213 // encInt64 encodes the int64 with address p.
214 func encInt64(i *encInstr, state *encoderState, p unsafe.Pointer) {
216 if v != 0 || state.sendZero {
222 // encInt64 encodes the uint64 with address p.
223 func encUint64(i *encInstr, state *encoderState, p unsafe.Pointer) {
225 if v != 0 || state.sendZero {
231 // encUintptr encodes the uintptr with address p.
232 func encUintptr(i *encInstr, state *encoderState, p unsafe.Pointer) {
233 v := uint64(*(*uintptr)(p))
234 if v != 0 || state.sendZero {
240 // floatBits returns a uint64 holding the bits of a floating-point number.
241 // Floating-point numbers are transmitted as uint64s holding the bits
242 // of the underlying representation. They are sent byte-reversed, with
243 // the exponent end coming out first, so integer floating point numbers
244 // (for example) transmit more compactly. This routine does the
246 func floatBits(f float64) uint64 {
247 u := math.Float64bits(f)
249 for i := 0; i < 8; i++ {
257 // encFloat32 encodes the float32 with address p.
258 func encFloat32(i *encInstr, state *encoderState, p unsafe.Pointer) {
260 if f != 0 || state.sendZero {
261 v := floatBits(float64(f))
267 // encFloat64 encodes the float64 with address p.
268 func encFloat64(i *encInstr, state *encoderState, p unsafe.Pointer) {
270 if f != 0 || state.sendZero {
277 // encComplex64 encodes the complex64 with address p.
278 // Complex numbers are just a pair of floating-point numbers, real part first.
279 func encComplex64(i *encInstr, state *encoderState, p unsafe.Pointer) {
280 c := *(*complex64)(p)
281 if c != 0+0i || state.sendZero {
282 rpart := floatBits(float64(real(c)))
283 ipart := floatBits(float64(imag(c)))
285 state.encodeUint(rpart)
286 state.encodeUint(ipart)
290 // encComplex128 encodes the complex128 with address p.
291 func encComplex128(i *encInstr, state *encoderState, p unsafe.Pointer) {
292 c := *(*complex128)(p)
293 if c != 0+0i || state.sendZero {
294 rpart := floatBits(real(c))
295 ipart := floatBits(imag(c))
297 state.encodeUint(rpart)
298 state.encodeUint(ipart)
302 // encUint8Array encodes the byte slice whose header has address p.
303 // Byte arrays are encoded as an unsigned count followed by the raw bytes.
304 func encUint8Array(i *encInstr, state *encoderState, p unsafe.Pointer) {
306 if len(b) > 0 || state.sendZero {
308 state.encodeUint(uint64(len(b)))
313 // encString encodes the string whose header has address p.
314 // Strings are encoded as an unsigned count followed by the raw bytes.
315 func encString(i *encInstr, state *encoderState, p unsafe.Pointer) {
317 if len(s) > 0 || state.sendZero {
319 state.encodeUint(uint64(len(s)))
320 state.b.WriteString(s)
324 // encStructTerminator encodes the end of an encoded struct
325 // as delta field number of 0.
326 func encStructTerminator(i *encInstr, state *encoderState, p unsafe.Pointer) {
332 // encEngine an array of instructions indexed by field number of the encoding
333 // data, typically a struct. It is executed top to bottom, walking the struct.
334 type encEngine struct {
338 const singletonField = 0
340 // encodeSingle encodes a single top-level non-struct value.
341 func (enc *Encoder) encodeSingle(b *bytes.Buffer, engine *encEngine, basep uintptr) {
342 state := enc.newEncoderState(b)
343 state.fieldnum = singletonField
344 // There is no surrounding struct to frame the transmission, so we must
345 // generate data even if the item is zero. To do this, set sendZero.
346 state.sendZero = true
347 instr := &engine.instr[singletonField]
348 p := unsafe.Pointer(basep) // offset will be zero
350 if p = encIndirect(p, instr.indir); p == nil {
354 instr.op(instr, state, p)
355 enc.freeEncoderState(state)
358 // encodeStruct encodes a single struct value.
359 func (enc *Encoder) encodeStruct(b *bytes.Buffer, engine *encEngine, basep uintptr) {
360 state := enc.newEncoderState(b)
362 for i := 0; i < len(engine.instr); i++ {
363 instr := &engine.instr[i]
364 p := unsafe.Pointer(basep + instr.offset)
366 if p = encIndirect(p, instr.indir); p == nil {
370 instr.op(instr, state, p)
372 enc.freeEncoderState(state)
375 // encodeArray encodes the array whose 0th element is at p.
376 func (enc *Encoder) encodeArray(b *bytes.Buffer, p uintptr, op encOp, elemWid uintptr, elemIndir int, length int) {
377 state := enc.newEncoderState(b)
379 state.sendZero = true
380 state.encodeUint(uint64(length))
381 for i := 0; i < length; i++ {
383 up := unsafe.Pointer(elemp)
385 if up = encIndirect(up, elemIndir); up == nil {
386 errorf("encodeArray: nil element")
390 op(nil, state, unsafe.Pointer(elemp))
391 p += uintptr(elemWid)
393 enc.freeEncoderState(state)
396 // encodeReflectValue is a helper for maps. It encodes the value v.
397 func encodeReflectValue(state *encoderState, v reflect.Value, op encOp, indir int) {
398 for i := 0; i < indir && v.IsValid(); i++ {
399 v = reflect.Indirect(v)
402 errorf("encodeReflectValue: nil element")
404 op(nil, state, unsafe.Pointer(unsafeAddr(v)))
407 // encodeMap encodes a map as unsigned count followed by key:value pairs.
408 // Because map internals are not exposed, we must use reflection rather than
410 func (enc *Encoder) encodeMap(b *bytes.Buffer, mv reflect.Value, keyOp, elemOp encOp, keyIndir, elemIndir int) {
411 state := enc.newEncoderState(b)
413 state.sendZero = true
415 state.encodeUint(uint64(len(keys)))
416 for _, key := range keys {
417 encodeReflectValue(state, key, keyOp, keyIndir)
418 encodeReflectValue(state, mv.MapIndex(key), elemOp, elemIndir)
420 enc.freeEncoderState(state)
423 // encodeInterface encodes the interface value iv.
424 // To send an interface, we send a string identifying the concrete type, followed
425 // by the type identifier (which might require defining that type right now), followed
426 // by the concrete value. A nil value gets sent as the empty string for the name,
427 // followed by no value.
428 func (enc *Encoder) encodeInterface(b *bytes.Buffer, iv reflect.Value) {
429 // Gobs can encode nil interface values but not typed interface
430 // values holding nil pointers, since nil pointers point to no value.
432 if elem.Kind() == reflect.Ptr && elem.IsNil() {
433 errorf("gob: cannot encode nil pointer of type %s inside interface", iv.Elem().Type())
435 state := enc.newEncoderState(b)
437 state.sendZero = true
443 ut := userType(iv.Elem().Type())
445 name, ok := concreteTypeToName[ut.base]
446 registerLock.RUnlock()
448 errorf("type not registered for interface: %s", ut.base)
451 state.encodeUint(uint64(len(name)))
452 _, err := state.b.WriteString(name)
456 // Define the type id if necessary.
457 enc.sendTypeDescriptor(enc.writer(), state, ut)
459 enc.sendTypeId(state, ut)
460 // Encode the value into a new buffer. Any nested type definitions
461 // should be written to b, before the encoded value.
463 data := new(bytes.Buffer)
464 data.Write(spaceForLength)
465 enc.encode(data, elem, ut)
470 enc.writeMessage(b, data)
474 enc.freeEncoderState(state)
477 // isZero returns whether the value is the zero of its type.
478 func isZero(val reflect.Value) bool {
481 for i := 0; i < val.Len(); i++ {
482 if !isZero(val.Index(i)) {
487 case reflect.Map, reflect.Slice, reflect.String:
488 return val.Len() == 0
491 case reflect.Complex64, reflect.Complex128:
492 return val.Complex() == 0
493 case reflect.Chan, reflect.Func, reflect.Ptr:
495 case reflect.Int, reflect.Int8, reflect.Int16, reflect.Int32, reflect.Int64:
496 return val.Int() == 0
497 case reflect.Float32, reflect.Float64:
498 return val.Float() == 0
499 case reflect.Uint, reflect.Uint8, reflect.Uint16, reflect.Uint32, reflect.Uint64, reflect.Uintptr:
500 return val.Uint() == 0
502 for i := 0; i < val.NumField(); i++ {
503 if !isZero(val.Field(i)) {
509 panic("unknown type in isZero " + val.Type().String())
512 // encGobEncoder encodes a value that implements the GobEncoder interface.
513 // The data is sent as a byte array.
514 func (enc *Encoder) encodeGobEncoder(b *bytes.Buffer, v reflect.Value) {
515 // TODO: should we catch panics from the called method?
516 // We know it's a GobEncoder, so just call the method directly.
517 data, err := v.Interface().(GobEncoder).GobEncode()
521 state := enc.newEncoderState(b)
523 state.encodeUint(uint64(len(data)))
525 enc.freeEncoderState(state)
528 var encOpTable = [...]encOp{
529 reflect.Bool: encBool,
531 reflect.Int8: encInt8,
532 reflect.Int16: encInt16,
533 reflect.Int32: encInt32,
534 reflect.Int64: encInt64,
535 reflect.Uint: encUint,
536 reflect.Uint8: encUint8,
537 reflect.Uint16: encUint16,
538 reflect.Uint32: encUint32,
539 reflect.Uint64: encUint64,
540 reflect.Uintptr: encUintptr,
541 reflect.Float32: encFloat32,
542 reflect.Float64: encFloat64,
543 reflect.Complex64: encComplex64,
544 reflect.Complex128: encComplex128,
545 reflect.String: encString,
548 // encOpFor returns (a pointer to) the encoding op for the base type under rt and
549 // the indirection count to reach it.
550 func (enc *Encoder) encOpFor(rt reflect.Type, inProgress map[reflect.Type]*encOp) (*encOp, int) {
552 // If the type implements GobEncoder, we handle it without further processing.
554 return enc.gobEncodeOpFor(ut)
556 // If this type is already in progress, it's a recursive type (e.g. map[string]*T).
557 // Return the pointer to the op we're already building.
558 if opPtr := inProgress[rt]; opPtr != nil {
559 return opPtr, ut.indir
565 if int(k) < len(encOpTable) {
571 switch t := typ; t.Kind() {
573 if t.Elem().Kind() == reflect.Uint8 {
577 // Slices have a header; we decode it to find the underlying array.
578 elemOp, indir := enc.encOpFor(t.Elem(), inProgress)
579 op = func(i *encInstr, state *encoderState, p unsafe.Pointer) {
580 slice := (*reflect.SliceHeader)(p)
581 if !state.sendZero && slice.Len == 0 {
585 state.enc.encodeArray(state.b, slice.Data, *elemOp, t.Elem().Size(), indir, int(slice.Len))
588 // True arrays have size in the type.
589 elemOp, indir := enc.encOpFor(t.Elem(), inProgress)
590 op = func(i *encInstr, state *encoderState, p unsafe.Pointer) {
592 state.enc.encodeArray(state.b, uintptr(p), *elemOp, t.Elem().Size(), indir, t.Len())
595 keyOp, keyIndir := enc.encOpFor(t.Key(), inProgress)
596 elemOp, elemIndir := enc.encOpFor(t.Elem(), inProgress)
597 op = func(i *encInstr, state *encoderState, p unsafe.Pointer) {
598 // Maps cannot be accessed by moving addresses around the way
599 // that slices etc. can. We must recover a full reflection value for
601 v := reflect.NewAt(t, unsafe.Pointer(p)).Elem()
602 mv := reflect.Indirect(v)
603 // We send zero-length (but non-nil) maps because the
604 // receiver might want to use the map. (Maps don't use append.)
605 if !state.sendZero && mv.IsNil() {
609 state.enc.encodeMap(state.b, mv, *keyOp, *elemOp, keyIndir, elemIndir)
612 // Generate a closure that calls out to the engine for the nested type.
613 enc.getEncEngine(userType(typ))
614 info := mustGetTypeInfo(typ)
615 op = func(i *encInstr, state *encoderState, p unsafe.Pointer) {
617 // indirect through info to delay evaluation for recursive structs
618 state.enc.encodeStruct(state.b, info.encoder, uintptr(p))
620 case reflect.Interface:
621 op = func(i *encInstr, state *encoderState, p unsafe.Pointer) {
622 // Interfaces transmit the name and contents of the concrete
623 // value they contain.
624 v := reflect.NewAt(t, unsafe.Pointer(p)).Elem()
625 iv := reflect.Indirect(v)
626 if !state.sendZero && (!iv.IsValid() || iv.IsNil()) {
630 state.enc.encodeInterface(state.b, iv)
635 errorf("can't happen: encode type %s", rt)
640 // gobEncodeOpFor returns the op for a type that is known to implement
642 func (enc *Encoder) gobEncodeOpFor(ut *userTypeInfo) (*encOp, int) {
644 if ut.encIndir == -1 {
645 rt = reflect.PtrTo(rt)
646 } else if ut.encIndir > 0 {
647 for i := int8(0); i < ut.encIndir; i++ {
652 op = func(i *encInstr, state *encoderState, p unsafe.Pointer) {
654 if ut.encIndir == -1 {
655 // Need to climb up one level to turn value into pointer.
656 v = reflect.NewAt(rt, unsafe.Pointer(&p)).Elem()
658 v = reflect.NewAt(rt, p).Elem()
660 if !state.sendZero && isZero(v) {
664 state.enc.encodeGobEncoder(state.b, v)
666 return &op, int(ut.encIndir) // encIndir: op will get called with p == address of receiver.
669 // compileEnc returns the engine to compile the type.
670 func (enc *Encoder) compileEnc(ut *userTypeInfo) *encEngine {
672 engine := new(encEngine)
673 seen := make(map[reflect.Type]*encOp)
678 if !ut.isGobEncoder &&
679 srt.Kind() == reflect.Struct {
680 for fieldNum, wireFieldNum := 0, 0; fieldNum < srt.NumField(); fieldNum++ {
681 f := srt.Field(fieldNum)
682 if !isExported(f.Name) {
685 op, indir := enc.encOpFor(f.Type, seen)
686 engine.instr = append(engine.instr, encInstr{*op, wireFieldNum, indir, uintptr(f.Offset)})
689 if srt.NumField() > 0 && len(engine.instr) == 0 {
690 errorf("type %s has no exported fields", rt)
692 engine.instr = append(engine.instr, encInstr{encStructTerminator, 0, 0, 0})
694 engine.instr = make([]encInstr, 1)
695 op, indir := enc.encOpFor(rt, seen)
696 engine.instr[0] = encInstr{*op, singletonField, indir, 0} // offset is zero
701 // getEncEngine returns the engine to compile the type.
702 // typeLock must be held (or we're in initialization and guaranteed single-threaded).
703 func (enc *Encoder) getEncEngine(ut *userTypeInfo) *encEngine {
704 info, err1 := getTypeInfo(ut)
708 if info.encoder == nil {
709 // Assign the encEngine now, so recursive types work correctly. But...
710 info.encoder = new(encEngine)
711 // ... if we fail to complete building the engine, don't cache the half-built machine.
712 // Doing this here means we won't cache a type that is itself OK but
713 // that contains a nested type that won't compile. The result is consistent
714 // error behavior when Encode is called multiple times on the top-level type.
721 info.encoder = enc.compileEnc(ut)
727 // lockAndGetEncEngine is a function that locks and compiles.
728 // This lets us hold the lock only while compiling, not when encoding.
729 func (enc *Encoder) lockAndGetEncEngine(ut *userTypeInfo) *encEngine {
731 defer typeLock.Unlock()
732 return enc.getEncEngine(ut)
735 func (enc *Encoder) encode(b *bytes.Buffer, value reflect.Value, ut *userTypeInfo) {
736 defer catchError(&enc.err)
737 engine := enc.lockAndGetEncEngine(ut)
740 indir = int(ut.encIndir)
742 for i := 0; i < indir; i++ {
743 value = reflect.Indirect(value)
745 if !ut.isGobEncoder && value.Type().Kind() == reflect.Struct {
746 enc.encodeStruct(b, engine, unsafeAddr(value))
748 enc.encodeSingle(b, engine, unsafeAddr(value))