-
Notifications
You must be signed in to change notification settings - Fork 15
/
doc.go
156 lines (156 loc) · 5.62 KB
/
doc.go
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
// Package protobuf implements Protocol Buffers reflectively
// using Go types to define message formats.
// This approach provides convenience similar to Gob encoding,
// but with a widely-used and language-neutral wire format.
// For general information on Protocol buffers see
// http://protobuf.googlecode.com.
//
// In contrast with goprotobuf,
// this package does not require users to write or compile .proto files;
// you just define the message formats you want as Go struct types.
// Consider for example this example message format definition
// from the Protocol Buffers overview:
//
// message Person {
// required string name = 1;
// required int32 id = 2;
// optional string email = 3;
//
// enum PhoneType {
// MOBILE = 0;
// HOME = 1;
// WORK = 2;
// }
//
// message PhoneNumber {
// required string number = 1;
// optional PhoneType type = 2;
// }
//
// repeated PhoneNumber phone = 4;
// }
//
// The following Go type and const definitions express exactly the same format,
// for purposes of encoding and decoding with this protobuf package:
//
// type Person struct {
// Name string
// Id int32
// Email *string
// Phone []PhoneNumber
// }
//
// type PhoneType uint32
// const (
// MOBILE PhoneType = iota
// HOME
// WORK
// )
//
// type PhoneNumber struct {
// Number string
// Type *PhoneType
// }
//
// To encode a message, you simply call the Encode() function
// with a pointer to the struct you wish to encode, and
// Encode() returns a []byte slice containing the protobuf-encoded struct:
//
// person := Person{...}
// buf := Encode(&person)
// output.Write(buf)
//
// To decode an encoded message, simply call Decode() on the byte-slice:
//
// err := Decode(buf,&person,nil)
// if err != nil {
// panic("Decode failed: "+err.Error())
// }
//
// If you want to interoperate with code in other languages
// using the same message formats, you may of course still end up writing
// .proto files for the code in those other languages.
// However, defining message formats with native Go types enables these types
// to be tailored to the code using them without affecting wire compatibility,
// such as by attaching useful methods to these struct types.
// The translation between a Go struct definition
// and a basic Protocol Buffers message format definition is straightforward;
// the rules are as follows.
//
// A message definition in a .proto file translates to a Go struct,
// whose fields are implicitly assigned consecutive numbers starting from 1.
// If you need to leave gaps in the field number sequence
// (e.g., to delete an obsolete field without breaking wire compatibility),
// then you can skip that field number using a blank Go field, like this:
//
// type Padded struct {
// Field1 string // = 1
// _ struct{} // = 2 (unused field number)
// Field2 int32 // = 3
// }
//
// A 'required' protobuf field translates to a plain field
// of a corresponding type in the Go struct.
// The following table summarizes the correspondence between
// .proto definition types and Go field types:
//
// Protobuf Go
// -------- --
// bool bool
// enum Enum
// int32 uint32
// int64 uint64
// uint32 uint32
// uint64 uint64
// sint32 int32
// sint64 int64
// fixed32 Ufixed32
// fixed64 Ufixed64
// sfixed32 Sfixed32
// sfixed64 Sfixed64
// float float32
// double float64
// string string
// bytes []byte
// message struct
//
// An 'optional' protobuf field is expressed as a pointer field in Go.
// Encode() will transmit the field only if the pointer is non-nil.
// Decode() will instantiate the pointed-to type and fill in the pointer
// if the field is present in the message being decoded,
// leaving the pointer unmodified (usually nil) if the field is not present.
//
// A 'repeated' protobuf field translates to a slice field in Go.
// Slices of primitive bool, integer, and float types are encoded
// and decoded in packed format, as if the [packed=true] option
// was declared for the field in the .proto file.
//
// For flexibility and convenience, struct fields may have interface types,
// which this package interprets as having dynamic types to be bound at runtime.
// Encode() follows the interface's implicit pointer and uses reflection
// to determine the referred-to object's actual type for encoding
// Decode() takes an optional map of interface types to constructor functions,
// which it uses to instantiate concrete types for interfaces while decoding.
// Furthermore, if the instantiated types support the Encoding interface,
// Encode() and Decode() will invoke the methods of that interface,
// allowing objects to implement their own custom encoding/decoding methods.
//
// This package does not try to support all possible protobuf formats.
// It currently does not support nonzero default value declarations for enums,
// the legacy unpacked formats for repeated numeric fields,
// messages with extremely sparse field numbering,
// or other more exotic features like extensions or oneof.
// If you need to interoperate with existing protobuf code using these features,
// then you should probably use goprotobuf,
// at least for those particular message formats.
//
// Another downside of this reflective approach to protobuf implementation
// is that reflective code is generally less efficient than
// statically generated code, as gogoprotobuf produces for example.
// If we decide we want the convenience of format definitions in Go
// with the runtime performance of static code generation,
// we could in principle achieve that by adding a "Go-format"
// message format compiler frontend to goprotobuf or gogoprotobuf -
// but we leave this as an exercise for the reader.
//
package protobuf