libgo/go/encoding/gob/type.go

   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.
   4
   5 package gob
   6
   7 import (
   8         "errors"
   9         "fmt"
  10         "os"
  11         "reflect"
  12         "sync"
  13         "unicode"
  14         "unicode/utf8"
  15 )
  16
  17 // userTypeInfo stores the information associated with a type the user has handed
  18 // to the package.  It's computed once and stored in a map keyed by reflection
  19 // type.
  20 type userTypeInfo struct {
  21         user         reflect.Type // the type the user handed us
  22         base         reflect.Type // the base type after all indirections
  23         indir        int          // number of indirections to reach the base type
  24         isGobEncoder bool         // does the type implement GobEncoder?
  25         isGobDecoder bool         // does the type implement GobDecoder?
  26         encIndir     int8         // number of indirections to reach the receiver type; may be negative
  27         decIndir     int8         // number of indirections to reach the receiver type; may be negative
  28 }
  29
  30 var (
  31         // Protected by an RWMutex because we read it a lot and write
  32         // it only when we see a new type, typically when compiling.
  33         userTypeLock  sync.RWMutex
  34         userTypeCache = make(map[reflect.Type]*userTypeInfo)
  35 )
  36
  37 // validType returns, and saves, the information associated with user-provided type rt.
  38 // If the user type is not valid, err will be non-nil.  To be used when the error handler
  39 // is not set up.
  40 func validUserType(rt reflect.Type) (ut *userTypeInfo, err error) {
  41         userTypeLock.RLock()
  42         ut = userTypeCache[rt]
  43         userTypeLock.RUnlock()
  44         if ut != nil {
  45                 return
  46         }
  47         // Now set the value under the write lock.
  48         userTypeLock.Lock()
  49         defer userTypeLock.Unlock()
  50         if ut = userTypeCache[rt]; ut != nil {
  51                 // Lost the race; not a problem.
  52                 return
  53         }
  54         ut = new(userTypeInfo)
  55         ut.base = rt
  56         ut.user = rt
  57         // A type that is just a cycle of pointers (such as type T *T) cannot
  58         // be represented in gobs, which need some concrete data.  We use a
  59         // cycle detection algorithm from Knuth, Vol 2, Section 3.1, Ex 6,
  60         // pp 539-540.  As we step through indirections, run another type at
  61         // half speed. If they meet up, there's a cycle.
  62         slowpoke := ut.base // walks half as fast as ut.base
  63         for {
  64                 pt := ut.base
  65                 if pt.Kind() != reflect.Ptr {
  66                         break
  67                 }
  68                 ut.base = pt.Elem()
  69                 if ut.base == slowpoke { // ut.base lapped slowpoke
  70                         // recursive pointer type.
  71                         return nil, errors.New("can't represent recursive pointer type " + ut.base.String())
  72                 }
  73                 if ut.indir%2 == 0 {
  74                         slowpoke = slowpoke.Elem()
  75                 }
  76                 ut.indir++
  77         }
  78         ut.isGobEncoder, ut.encIndir = implementsInterface(ut.user, gobEncoderInterfaceType)
  79         ut.isGobDecoder, ut.decIndir = implementsInterface(ut.user, gobDecoderInterfaceType)
  80         userTypeCache[rt] = ut
  81         return
  82 }
  83
  84 var (
  85         gobEncoderInterfaceType = reflect.TypeOf((*GobEncoder)(nil)).Elem()
  86         gobDecoderInterfaceType = reflect.TypeOf((*GobDecoder)(nil)).Elem()
  87 )
  88
  89 // implementsInterface reports whether the type implements the
  90 // gobEncoder/gobDecoder interface.
  91 // It also returns the number of indirections required to get to the
  92 // implementation.
  93 func implementsInterface(typ, gobEncDecType reflect.Type) (success bool, indir int8) {
  94         if typ == nil {
  95                 return
  96         }
  97         rt := typ
  98         // The type might be a pointer and we need to keep
  99         // dereferencing to the base type until we find an implementation.
 100         for {
 101                 if rt.Implements(gobEncDecType) {
 102                         return true, indir
 103                 }
 104                 if p := rt; p.Kind() == reflect.Ptr {
 105                         indir++
 106                         if indir > 100 { // insane number of indirections
 107                                 return false, 0
 108                         }
 109                         rt = p.Elem()
 110                         continue
 111                 }
 112                 break
 113         }
 114         // No luck yet, but if this is a base type (non-pointer), the pointer might satisfy.
 115         if typ.Kind() != reflect.Ptr {
 116                 // Not a pointer, but does the pointer work?
 117                 if reflect.PtrTo(typ).Implements(gobEncDecType) {
 118                         return true, -1
 119                 }
 120         }
 121         return false, 0
 122 }
 123
 124 // userType returns, and saves, the information associated with user-provided type rt.
 125 // If the user type is not valid, it calls error.
 126 func userType(rt reflect.Type) *userTypeInfo {
 127         ut, err := validUserType(rt)
 128         if err != nil {
 129                 error_(err)
 130         }
 131         return ut
 132 }
 133
 134 // A typeId represents a gob Type as an integer that can be passed on the wire.
 135 // Internally, typeIds are used as keys to a map to recover the underlying type info.
 136 type typeId int32
 137
 138 var nextId typeId       // incremented for each new type we build
 139 var typeLock sync.Mutex // set while building a type
 140 const firstUserId = 64  // lowest id number granted to user
 141
 142 type gobType interface {
 143         id() typeId
 144         setId(id typeId)
 145         name() string
 146         string() string // not public; only for debugging
 147         safeString(seen map[typeId]bool) string
 148 }
 149
 150 var types = make(map[reflect.Type]gobType)
 151 var idToType = make(map[typeId]gobType)
 152 var builtinIdToType map[typeId]gobType // set in init() after builtins are established
 153
 154 func setTypeId(typ gobType) {
 155         nextId++
 156         typ.setId(nextId)
 157         idToType[nextId] = typ
 158 }
 159
 160 func (t typeId) gobType() gobType {
 161         if t == 0 {
 162                 return nil
 163         }
 164         return idToType[t]
 165 }
 166
 167 // string returns the string representation of the type associated with the typeId.
 168 func (t typeId) string() string {
 169         if t.gobType() == nil {
 170                 return "<nil>"
 171         }
 172         return t.gobType().string()
 173 }
 174
 175 // Name returns the name of the type associated with the typeId.
 176 func (t typeId) name() string {
 177         if t.gobType() == nil {
 178                 return "<nil>"
 179         }
 180         return t.gobType().name()
 181 }
 182
 183 // Common elements of all types.
 184 type CommonType struct {
 185         Name string
 186         Id   typeId
 187 }
 188
 189 func (t *CommonType) id() typeId { return t.Id }
 190
 191 func (t *CommonType) setId(id typeId) { t.Id = id }
 192
 193 func (t *CommonType) string() string { return t.Name }
 194
 195 func (t *CommonType) safeString(seen map[typeId]bool) string {
 196         return t.Name
 197 }
 198
 199 func (t *CommonType) name() string { return t.Name }
 200
 201 // Create and check predefined types
 202 // The string for tBytes is "bytes" not "[]byte" to signify its specialness.
 203
 204 var (
 205         // Primordial types, needed during initialization.
 206         // Always passed as pointers so the interface{} type
 207         // goes through without losing its interfaceness.
 208         tBool      = bootstrapType("bool", (*bool)(nil), 1)
 209         tInt       = bootstrapType("int", (*int)(nil), 2)
 210         tUint      = bootstrapType("uint", (*uint)(nil), 3)
 211         tFloat     = bootstrapType("float", (*float64)(nil), 4)
 212         tBytes     = bootstrapType("bytes", (*[]byte)(nil), 5)
 213         tString    = bootstrapType("string", (*string)(nil), 6)
 214         tComplex   = bootstrapType("complex", (*complex128)(nil), 7)
 215         tInterface = bootstrapType("interface", (*interface{})(nil), 8)
 216         // Reserve some Ids for compatible expansion
 217         tReserved7 = bootstrapType("_reserved1", (*struct{ r7 int })(nil), 9)
 218         tReserved6 = bootstrapType("_reserved1", (*struct{ r6 int })(nil), 10)
 219         tReserved5 = bootstrapType("_reserved1", (*struct{ r5 int })(nil), 11)
 220         tReserved4 = bootstrapType("_reserved1", (*struct{ r4 int })(nil), 12)
 221         tReserved3 = bootstrapType("_reserved1", (*struct{ r3 int })(nil), 13)
 222         tReserved2 = bootstrapType("_reserved1", (*struct{ r2 int })(nil), 14)
 223         tReserved1 = bootstrapType("_reserved1", (*struct{ r1 int })(nil), 15)
 224 )
 225
 226 // Predefined because it's needed by the Decoder
 227 var tWireType = mustGetTypeInfo(reflect.TypeOf(wireType{})).id
 228 var wireTypeUserInfo *userTypeInfo // userTypeInfo of (*wireType)
 229
 230 func init() {
 231         // Some magic numbers to make sure there are no surprises.
 232         checkId(16, tWireType)
 233         checkId(17, mustGetTypeInfo(reflect.TypeOf(arrayType{})).id)
 234         checkId(18, mustGetTypeInfo(reflect.TypeOf(CommonType{})).id)
 235         checkId(19, mustGetTypeInfo(reflect.TypeOf(sliceType{})).id)
 236         checkId(20, mustGetTypeInfo(reflect.TypeOf(structType{})).id)
 237         checkId(21, mustGetTypeInfo(reflect.TypeOf(fieldType{})).id)
 238         checkId(23, mustGetTypeInfo(reflect.TypeOf(mapType{})).id)
 239
 240         builtinIdToType = make(map[typeId]gobType)
 241         for k, v := range idToType {
 242                 builtinIdToType[k] = v
 243         }
 244
 245         // Move the id space upwards to allow for growth in the predefined world
 246         // without breaking existing files.
 247         if nextId > firstUserId {
 248                 panic(fmt.Sprintln("nextId too large:", nextId))
 249         }
 250         nextId = firstUserId
 251         registerBasics()
 252         wireTypeUserInfo = userType(reflect.TypeOf((*wireType)(nil)))
 253 }
 254
 255 // Array type
 256 type arrayType struct {
 257         CommonType
 258         Elem typeId
 259         Len  int
 260 }
 261
 262 func newArrayType(name string) *arrayType {
 263         a := &arrayType{CommonType{Name: name}, 0, 0}
 264         return a
 265 }
 266
 267 func (a *arrayType) init(elem gobType, len int) {
 268         // Set our type id before evaluating the element's, in case it's our own.
 269         setTypeId(a)
 270         a.Elem = elem.id()
 271         a.Len = len
 272 }
 273
 274 func (a *arrayType) safeString(seen map[typeId]bool) string {
 275         if seen[a.Id] {
 276                 return a.Name
 277         }
 278         seen[a.Id] = true
 279         return fmt.Sprintf("[%d]%s", a.Len, a.Elem.gobType().safeString(seen))
 280 }
 281
 282 func (a *arrayType) string() string { return a.safeString(make(map[typeId]bool)) }
 283
 284 // GobEncoder type (something that implements the GobEncoder interface)
 285 type gobEncoderType struct {
 286         CommonType
 287 }
 288
 289 func newGobEncoderType(name string) *gobEncoderType {
 290         g := &gobEncoderType{CommonType{Name: name}}
 291         setTypeId(g)
 292         return g
 293 }
 294
 295 func (g *gobEncoderType) safeString(seen map[typeId]bool) string {
 296         return g.Name
 297 }
 298
 299 func (g *gobEncoderType) string() string { return g.Name }
 300
 301 // Map type
 302 type mapType struct {
 303         CommonType
 304         Key  typeId
 305         Elem typeId
 306 }
 307
 308 func newMapType(name string) *mapType {
 309         m := &mapType{CommonType{Name: name}, 0, 0}
 310         return m
 311 }
 312
 313 func (m *mapType) init(key, elem gobType) {
 314         // Set our type id before evaluating the element's, in case it's our own.
 315         setTypeId(m)
 316         m.Key = key.id()
 317         m.Elem = elem.id()
 318 }
 319
 320 func (m *mapType) safeString(seen map[typeId]bool) string {
 321         if seen[m.Id] {
 322                 return m.Name
 323         }
 324         seen[m.Id] = true
 325         key := m.Key.gobType().safeString(seen)
 326         elem := m.Elem.gobType().safeString(seen)
 327         return fmt.Sprintf("map[%s]%s", key, elem)
 328 }
 329
 330 func (m *mapType) string() string { return m.safeString(make(map[typeId]bool)) }
 331
 332 // Slice type
 333 type sliceType struct {
 334         CommonType
 335         Elem typeId
 336 }
 337
 338 func newSliceType(name string) *sliceType {
 339         s := &sliceType{CommonType{Name: name}, 0}
 340         return s
 341 }
 342
 343 func (s *sliceType) init(elem gobType) {
 344         // Set our type id before evaluating the element's, in case it's our own.
 345         setTypeId(s)
 346         s.Elem = elem.id()
 347 }
 348
 349 func (s *sliceType) safeString(seen map[typeId]bool) string {
 350         if seen[s.Id] {
 351                 return s.Name
 352         }
 353         seen[s.Id] = true
 354         return fmt.Sprintf("[]%s", s.Elem.gobType().safeString(seen))
 355 }
 356
 357 func (s *sliceType) string() string { return s.safeString(make(map[typeId]bool)) }
 358
 359 // Struct type
 360 type fieldType struct {
 361         Name string
 362         Id   typeId
 363 }
 364
 365 type structType struct {
 366         CommonType
 367         Field []*fieldType
 368 }
 369
 370 func (s *structType) safeString(seen map[typeId]bool) string {
 371         if s == nil {
 372                 return "<nil>"
 373         }
 374         if _, ok := seen[s.Id]; ok {
 375                 return s.Name
 376         }
 377         seen[s.Id] = true
 378         str := s.Name + " = struct { "
 379         for _, f := range s.Field {
 380                 str += fmt.Sprintf("%s %s; ", f.Name, f.Id.gobType().safeString(seen))
 381         }
 382         str += "}"
 383         return str
 384 }
 385
 386 func (s *structType) string() string { return s.safeString(make(map[typeId]bool)) }
 387
 388 func newStructType(name string) *structType {
 389         s := &structType{CommonType{Name: name}, nil}
 390         // For historical reasons we set the id here rather than init.
 391         // See the comment in newTypeObject for details.
 392         setTypeId(s)
 393         return s
 394 }
 395
 396 // newTypeObject allocates a gobType for the reflection type rt.
 397 // Unless ut represents a GobEncoder, rt should be the base type
 398 // of ut.
 399 // This is only called from the encoding side. The decoding side
 400 // works through typeIds and userTypeInfos alone.
 401 func newTypeObject(name string, ut *userTypeInfo, rt reflect.Type) (gobType, error) {
 402         // Does this type implement GobEncoder?
 403         if ut.isGobEncoder {
 404                 return newGobEncoderType(name), nil
 405         }
 406         var err error
 407         var type0, type1 gobType
 408         defer func() {
 409                 if err != nil {
 410                         delete(types, rt)
 411                 }
 412         }()
 413         // Install the top-level type before the subtypes (e.g. struct before
 414         // fields) so recursive types can be constructed safely.
 415         switch t := rt; t.Kind() {
 416         // All basic types are easy: they are predefined.
 417         case reflect.Bool:
 418                 return tBool.gobType(), nil
 419
 420         case reflect.Int, reflect.Int8, reflect.Int16, reflect.Int32, reflect.Int64:
 421                 return tInt.gobType(), nil
 422
 423         case reflect.Uint, reflect.Uint8, reflect.Uint16, reflect.Uint32, reflect.Uint64, reflect.Uintptr:
 424                 return tUint.gobType(), nil
 425
 426         case reflect.Float32, reflect.Float64:
 427                 return tFloat.gobType(), nil
 428
 429         case reflect.Complex64, reflect.Complex128:
 430                 return tComplex.gobType(), nil
 431
 432         case reflect.String:
 433                 return tString.gobType(), nil
 434
 435         case reflect.Interface:
 436                 return tInterface.gobType(), nil
 437
 438         case reflect.Array:
 439                 at := newArrayType(name)
 440                 types[rt] = at
 441                 type0, err = getBaseType("", t.Elem())
 442                 if err != nil {
 443                         return nil, err
 444                 }
 445                 // Historical aside:
 446                 // For arrays, maps, and slices, we set the type id after the elements
 447                 // are constructed. This is to retain the order of type id allocation after
 448                 // a fix made to handle recursive types, which changed the order in
 449                 // which types are built.  Delaying the setting in this way preserves
 450                 // type ids while allowing recursive types to be described. Structs,
 451                 // done below, were already handling recursion correctly so they
 452                 // assign the top-level id before those of the field.
 453                 at.init(type0, t.Len())
 454                 return at, nil
 455
 456         case reflect.Map:
 457                 mt := newMapType(name)
 458                 types[rt] = mt
 459                 type0, err = getBaseType("", t.Key())
 460                 if err != nil {
 461                         return nil, err
 462                 }
 463                 type1, err = getBaseType("", t.Elem())
 464                 if err != nil {
 465                         return nil, err
 466                 }
 467                 mt.init(type0, type1)
 468                 return mt, nil
 469
 470         case reflect.Slice:
 471                 // []byte == []uint8 is a special case
 472                 if t.Elem().Kind() == reflect.Uint8 {
 473                         return tBytes.gobType(), nil
 474                 }
 475                 st := newSliceType(name)
 476                 types[rt] = st
 477                 type0, err = getBaseType(t.Elem().Name(), t.Elem())
 478                 if err != nil {
 479                         return nil, err
 480                 }
 481                 st.init(type0)
 482                 return st, nil
 483
 484         case reflect.Struct:
 485                 st := newStructType(name)
 486                 types[rt] = st
 487                 idToType[st.id()] = st
 488                 for i := 0; i < t.NumField(); i++ {
 489                         f := t.Field(i)
 490                         if !isExported(f.Name) {
 491                                 continue
 492                         }
 493                         typ := userType(f.Type).base
 494                         tname := typ.Name()
 495                         if tname == "" {
 496                                 t := userType(f.Type).base
 497                                 tname = t.String()
 498                         }
 499                         gt, err := getBaseType(tname, f.Type)
 500                         if err != nil {
 501                                 return nil, err
 502                         }
 503                         st.Field = append(st.Field, &fieldType{f.Name, gt.id()})
 504                 }
 505                 return st, nil
 506
 507         default:
 508                 return nil, errors.New("gob NewTypeObject can't handle type: " + rt.String())
 509         }
 510         return nil, nil
 511 }
 512
 513 // isExported reports whether this is an exported - upper case - name.
 514 func isExported(name string) bool {
 515         rune, _ := utf8.DecodeRuneInString(name)
 516         return unicode.IsUpper(rune)
 517 }
 518
 519 // getBaseType returns the Gob type describing the given reflect.Type's base type.
 520 // typeLock must be held.
 521 func getBaseType(name string, rt reflect.Type) (gobType, error) {
 522         ut := userType(rt)
 523         return getType(name, ut, ut.base)
 524 }
 525
 526 // getType returns the Gob type describing the given reflect.Type.
 527 // Should be called only when handling GobEncoders/Decoders,
 528 // which may be pointers.  All other types are handled through the
 529 // base type, never a pointer.
 530 // typeLock must be held.
 531 func getType(name string, ut *userTypeInfo, rt reflect.Type) (gobType, error) {
 532         typ, present := types[rt]
 533         if present {
 534                 return typ, nil
 535         }
 536         typ, err := newTypeObject(name, ut, rt)
 537         if err == nil {
 538                 types[rt] = typ
 539         }
 540         return typ, err
 541 }
 542
 543 func checkId(want, got typeId) {
 544         if want != got {
 545                 fmt.Fprintf(os.Stderr, "checkId: %d should be %d\n", int(got), int(want))
 546                 panic("bootstrap type wrong id: " + got.name() + " " + got.string() + " not " + want.string())
 547         }
 548 }
 549
 550 // used for building the basic types; called only from init().  the incoming
 551 // interface always refers to a pointer.
 552 func bootstrapType(name string, e interface{}, expect typeId) typeId {
 553         rt := reflect.TypeOf(e).Elem()
 554         _, present := types[rt]
 555         if present {
 556                 panic("bootstrap type already present: " + name + ", " + rt.String())
 557         }
 558         typ := &CommonType{Name: name}
 559         types[rt] = typ
 560         setTypeId(typ)
 561         checkId(expect, nextId)
 562         userType(rt) // might as well cache it now
 563         return nextId
 564 }
 565
 566 // Representation of the information we send and receive about this type.
 567 // Each value we send is preceded by its type definition: an encoded int.
 568 // However, the very first time we send the value, we first send the pair
 569 // (-id, wireType).
 570 // For bootstrapping purposes, we assume that the recipient knows how
 571 // to decode a wireType; it is exactly the wireType struct here, interpreted
 572 // using the gob rules for sending a structure, except that we assume the
 573 // ids for wireType and structType etc. are known.  The relevant pieces
 574 // are built in encode.go's init() function.
 575 // To maintain binary compatibility, if you extend this type, always put
 576 // the new fields last.
 577 type wireType struct {
 578         ArrayT      *arrayType
 579         SliceT      *sliceType
 580         StructT     *structType
 581         MapT        *mapType
 582         GobEncoderT *gobEncoderType
 583 }
 584
 585 func (w *wireType) string() string {
 586         const unknown = "unknown type"
 587         if w == nil {
 588                 return unknown
 589         }
 590         switch {
 591         case w.ArrayT != nil:
 592                 return w.ArrayT.Name
 593         case w.SliceT != nil:
 594                 return w.SliceT.Name
 595         case w.StructT != nil:
 596                 return w.StructT.Name
 597         case w.MapT != nil:
 598                 return w.MapT.Name
 599         case w.GobEncoderT != nil:
 600                 return w.GobEncoderT.Name
 601         }
 602         return unknown
 603 }
 604
 605 type typeInfo struct {
 606         id      typeId
 607         encoder *encEngine
 608         wire    *wireType
 609 }
 610
 611 var typeInfoMap = make(map[reflect.Type]*typeInfo) // protected by typeLock
 612
 613 // typeLock must be held.
 614 func getTypeInfo(ut *userTypeInfo) (*typeInfo, error) {
 615         rt := ut.base
 616         if ut.isGobEncoder {
 617                 // We want the user type, not the base type.
 618                 rt = ut.user
 619         }
 620         info, ok := typeInfoMap[rt]
 621         if ok {
 622                 return info, nil
 623         }
 624         info = new(typeInfo)
 625         gt, err := getBaseType(rt.Name(), rt)
 626         if err != nil {
 627                 return nil, err
 628         }
 629         info.id = gt.id()
 630
 631         if ut.isGobEncoder {
 632                 userType, err := getType(rt.Name(), ut, rt)
 633                 if err != nil {
 634                         return nil, err
 635                 }
 636                 info.wire = &wireType{GobEncoderT: userType.id().gobType().(*gobEncoderType)}
 637                 typeInfoMap[ut.user] = info
 638                 return info, nil
 639         }
 640
 641         t := info.id.gobType()
 642         switch typ := rt; typ.Kind() {
 643         case reflect.Array:
 644                 info.wire = &wireType{ArrayT: t.(*arrayType)}
 645         case reflect.Map:
 646                 info.wire = &wireType{MapT: t.(*mapType)}
 647         case reflect.Slice:
 648                 // []byte == []uint8 is a special case handled separately
 649                 if typ.Elem().Kind() != reflect.Uint8 {
 650                         info.wire = &wireType{SliceT: t.(*sliceType)}
 651                 }
 652         case reflect.Struct:
 653                 info.wire = &wireType{StructT: t.(*structType)}
 654         }
 655         typeInfoMap[rt] = info
 656         return info, nil
 657 }
 658
 659 // Called only when a panic is acceptable and unexpected.
 660 func mustGetTypeInfo(rt reflect.Type) *typeInfo {
 661         t, err := getTypeInfo(userType(rt))
 662         if err != nil {
 663                 panic("getTypeInfo: " + err.Error())
 664         }
 665         return t
 666 }
 667
 668 // GobEncoder is the interface describing data that provides its own
 669 // representation for encoding values for transmission to a GobDecoder.
 670 // A type that implements GobEncoder and GobDecoder has complete
 671 // control over the representation of its data and may therefore
 672 // contain things such as private fields, channels, and functions,
 673 // which are not usually transmissible in gob streams.
 674 //
 675 // Note: Since gobs can be stored permanently, It is good design
 676 // to guarantee the encoding used by a GobEncoder is stable as the
 677 // software evolves.  For instance, it might make sense for GobEncode
 678 // to include a version number in the encoding.
 679 type GobEncoder interface {
 680         // GobEncode returns a byte slice representing the encoding of the
 681         // receiver for transmission to a GobDecoder, usually of the same
 682         // concrete type.
 683         GobEncode() ([]byte, error)
 684 }
 685
 686 // GobDecoder is the interface describing data that provides its own
 687 // routine for decoding transmitted values sent by a GobEncoder.
 688 type GobDecoder interface {
 689         // GobDecode overwrites the receiver, which must be a pointer,
 690         // with the value represented by the byte slice, which was written
 691         // by GobEncode, usually for the same concrete type.
 692         GobDecode([]byte) error
 693 }
 694
 695 var (
 696         nameToConcreteType = make(map[string]reflect.Type)
 697         concreteTypeToName = make(map[reflect.Type]string)
 698 )
 699
 700 // RegisterName is like Register but uses the provided name rather than the
 701 // type's default.
 702 func RegisterName(name string, value interface{}) {
 703         if name == "" {
 704                 // reserved for nil
 705                 panic("attempt to register empty name")
 706         }
 707         ut := userType(reflect.TypeOf(value))
 708         // Check for incompatible duplicates. The name must refer to the
 709         // same user type, and vice versa.
 710         if t, ok := nameToConcreteType[name]; ok && t != ut.user {
 711                 panic(fmt.Sprintf("gob: registering duplicate types for %q: %s != %s", name, t, ut.user))
 712         }
 713         if n, ok := concreteTypeToName[ut.base]; ok && n != name {
 714                 panic(fmt.Sprintf("gob: registering duplicate names for %s: %q != %q", ut.user, n, name))
 715         }
 716         // Store the name and type provided by the user....
 717         nameToConcreteType[name] = reflect.TypeOf(value)
 718         // but the flattened type in the type table, since that's what decode needs.
 719         concreteTypeToName[ut.base] = name
 720 }
 721
 722 // Register records a type, identified by a value for that type, under its
 723 // internal type name.  That name will identify the concrete type of a value
 724 // sent or received as an interface variable.  Only types that will be
 725 // transferred as implementations of interface values need to be registered.
 726 // Expecting to be used only during initialization, it panics if the mapping
 727 // between types and names is not a bijection.
 728 func Register(value interface{}) {
 729         // Default to printed representation for unnamed types
 730         rt := reflect.TypeOf(value)
 731         name := rt.String()
 732
 733         // But for named types (or pointers to them), qualify with import path.
 734         // Dereference one pointer looking for a named type.
 735         star := ""
 736         if rt.Name() == "" {
 737                 if pt := rt; pt.Kind() == reflect.Ptr {
 738                         star = "*"
 739                         rt = pt
 740                 }
 741         }
 742         if rt.Name() != "" {
 743                 if rt.PkgPath() == "" {
 744                         name = star + rt.Name()
 745                 } else {
 746                         name = star + rt.PkgPath() + "." + rt.Name()
 747                 }
 748         }
 749
 750         RegisterName(name, value)
 751 }
 752
 753 func registerBasics() {
 754         Register(int(0))
 755         Register(int8(0))
 756         Register(int16(0))
 757         Register(int32(0))
 758         Register(int64(0))
 759         Register(uint(0))
 760         Register(uint8(0))
 761         Register(uint16(0))
 762         Register(uint32(0))
 763         Register(uint64(0))
 764         Register(float32(0))
 765         Register(float64(0))
 766         Register(complex64(0i))
 767         Register(complex128(0i))
 768         Register(uintptr(0))
 769         Register(false)
 770         Register("")
 771         Register([]byte(nil))
 772         Register([]int(nil))
 773         Register([]int8(nil))
 774         Register([]int16(nil))
 775         Register([]int32(nil))
 776         Register([]int64(nil))
 777         Register([]uint(nil))
 778         Register([]uint8(nil))
 779         Register([]uint16(nil))
 780         Register([]uint32(nil))
 781         Register([]uint64(nil))
 782         Register([]float32(nil))
 783         Register([]float64(nil))
 784         Register([]complex64(nil))
 785         Register([]complex128(nil))
 786         Register([]uintptr(nil))
 787         Register([]bool(nil))
 788         Register([]string(nil))
 789 }