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