The gob package

Gob is a serialisation technique specific to Go. It is designed to encode Go data types specifically and does not at present have support for or by any other languages. It supports all Go data types except for channels and functions. It supports integers of all types and sizes, strings and booleans, structs, arrays and slices. At present it has some problems with circular structures such as rings, but that will improve over time.

Gob encodes type information into its serialised forms. This is far more extensive than the type information in say an X.509 serialisation, but far more efficient than the type information contained in an XML document. Type information is only included once for each piece of data, but includes, for example, the names of struct fields.

This inclusion of type information makes Gob marshalling and unmarshalling fairly robust to changes or differences between the marshaller and unmarshaller. For example, a struct

  1. struct T {
  2.     a int
  3.     b int
  4. }

can be marshalled and then unmarshalled into a different struct

  1. struct T {
  2.     b int
  3.     a int
  4. }

where the order of fields has changed. It can also cope with missing fields (the values are ignored) or extra fields (the fields are left unchanged). It can cope with pointer types, so that the above struct could be unmarshalled into

  1. struct T {
  2.     *a int
  3.     **b int
  4. }

To some extent it can cope with type coercions so that an int field can be broadened into an int64, but not with incompatible types such as int and uint.

To use Gob to marshall a data value, you first need to create an Encoder. This takes a Writer as parameter and marshalling will be done to this write stream. The encoder has a method Encode which marshalls the value to the stream. This method can be called multiple times on multiple pieces of data. Type information for each data type is only written once, though.

You use a Decoder to unmarshall the serialised data stream. This takes a Reader and each read returns an unmarshalled data value.

A program to store gob serialised data into a file is

  1. /* SaveGob
  2.  */
  4. package main
  6. import (
  7.     "fmt"
  8.     "os"
  9.     "encoding/gob"
  10. )
  12. type Person struct {
  13.     Name  Name
  14.     Email []Email
  15. }
  17. type Name struct {
  18.     Family   string
  19.     Personal string
  20. }
  22. type Email struct {
  23.     Kind    string
  24.     Address string
  25. }
  27. func main() {
  28.     person := Person{
  29.         Name: Name{Family: "Newmarch", Personal: "Jan"},
  30.         Email: []Email{Email{Kind: "home", Address: "jan@newmarch.name"},
  31.             Email{Kind: "work", Address: "j.newmarch@boxhill.edu.au"}}}
  33.     saveGob("person.gob", person)
  34. }
  36. func saveGob(fileName string, key interface{}) {
  37.     outFile, err := os.Create(fileName)
  38.     checkError(err)
  39.     encoder := gob.NewEncoder(outFile)
  40.     err = encoder.Encode(key)
  41.     checkError(err)
  42.     outFile.Close()
  43. }
  45. func checkError(err error) {
  46.     if err != nil {
  47.         fmt.Println("Fatal error ", err.Error())
  48.         os.Exit(1)
  49.     }
  50. }

and to load it back into memory is

  1. /* LoadGob
  2.  */
  4. package main
  6. import (
  7.     "fmt"
  8.     "os"
  9.     "encoding/gob"
  10. )
  12. type Person struct {
  13.     Name  Name
  14.     Email []Email
  15. }
  17. type Name struct {
  18.     Family   string
  19.     Personal string
  20. }
  22. type Email struct {
  23.     Kind    string
  24.     Address string
  25. }
  27. func (p Person) String() string {
  28.     s := p.Name.Personal + " " + p.Name.Family
  29.     for _, v := range p.Email {
  30.         s += "\n" + v.Kind + ": " + v.Address
  31.     }
  32.     return s
  33. }
  34. func main() {
  35.     var person Person
  36.     loadGob("person.gob", &person)
  38.     fmt.Println("Person", person.String())
  39. }
  41. func loadGob(fileName string, key interface{}) {
  42.     inFile, err := os.Open(fileName)
  43.     checkError(err)
  44.     decoder := gob.NewDecoder(inFile)
  45.     err = decoder.Decode(key)
  46.     checkError(err)
  47.     inFile.Close()
  48. }
  50. func checkError(err error) {
  51.     if err != nil {
  52.         fmt.Println("Fatal error ", err.Error())
  53.         os.Exit(1)
  54.     }
  55. }

A client and server

A client to send a person’s data and read it back ten times is

  1. /* Gob EchoClient
  2.  */
  3. package main
  5. import (
  6.     "fmt"
  7.     "net"
  8.     "os"
  9.     "encoding/gob"
  10.     "bytes"
  11.     "io"
  12. )
  14. type Person struct {
  15.     Name  Name
  16.     Email []Email
  17. }
  19. type Name struct {
  20.     Family   string
  21.     Personal string
  22. }
  24. type Email struct {
  25.     Kind    string
  26.     Address string
  27. }
  29. func (p Person) String() string {
  30.     s := p.Name.Personal + " " + p.Name.Family
  31.     for _, v := range p.Email {
  32.         s += "\n" + v.Kind + ": " + v.Address
  33.     }
  34.     return s
  35. }
  37. func main() {
  38.     person := Person{
  39.         Name: Name{Family: "Newmarch", Personal: "Jan"},
  40.         Email: []Email{Email{Kind: "home", Address: "jan@newmarch.name"},
  41.             Email{Kind: "work", Address: "j.newmarch@boxhill.edu.au"}}}
  43.     if len(os.Args) != 2 {
  44.         fmt.Println("Usage: ", os.Args[0], "host:port")
  45.         os.Exit(1)
  46.     }
  47.     service := os.Args[1]
  49.     conn, err := net.Dial("tcp", service)
  50.     checkError(err)
  52.     encoder := gob.NewEncoder(conn)
  53.     decoder := gob.NewDecoder(conn)
  55.     for n := 0; n < 10; n++ {
  56.         encoder.Encode(person)
  57.         var newPerson Person
  58.         decoder.Decode(&newPerson)
  59.         fmt.Println(newPerson.String())
  60.     }
  62.     os.Exit(0)
  63. }
  65. func checkError(err error) {
  66.     if err != nil {
  67.         fmt.Println("Fatal error ", err.Error())
  68.         os.Exit(1)
  69.     }
  70. }

and the corrsponding server is

  1. /* Gob EchoServer
  2.  */
  3. package main
  5. import (
  6.     "fmt"
  7.     "net"
  8.     "os"
  9.     "encoding/gob"
  10. )
  12. type Person struct {
  13.     Name  Name
  14.     Email []Email
  15. }
  17. type Name struct {
  18.     Family   string
  19.     Personal string
  20. }
  22. type Email struct {
  23.     Kind    string
  24.     Address string
  25. }
  27. func (p Person) String() string {
  28.     s := p.Name.Personal + " " + p.Name.Family
  29.     for _, v := range p.Email {
  30.         s += "\n" + v.Kind + ": " + v.Address
  31.     }
  32.     return s
  33. }
  35. func main() {
  37.     service := "0.0.0.0:1200"
  38.     tcpAddr, err := net.ResolveTCPAddr("tcp", service)
  39.     checkError(err)
  41.     listener, err := net.ListenTCP("tcp", tcpAddr)
  42.     checkError(err)
  44.     for {
  45.         conn, err := listener.Accept()
  46.         if err != nil {
  47.             continue
  48.         }
  50.         encoder := gob.NewEncoder(conn)
  51.         decoder := gob.NewDecoder(conn)
  53.         for n := 0; n < 10; n++ {
  54.             var person Person
  55.             decoder.Decode(&person)
  56.             fmt.Println(person.String())
  57.             encoder.Encode(person)
  58.         }
  59.         conn.Close() // we're finished
  60.     }
  61. }
  63. func checkError(err error) {
  64.     if err != nil {
  65.         fmt.Println("Fatal error ", err.Error())
  66.         os.Exit(1)
  67.     }
  68. }