Goby3  3.1.5a
2024.05.23
message_lite.h
Go to the documentation of this file.
1 // Protocol Buffers - Google's data interchange format
2 // Copyright 2008 Google Inc. All rights reserved.
3 // https://developers.google.com/protocol-buffers/
4 //
5 // Redistribution and use in source and binary forms, with or without
6 // modification, are permitted provided that the following conditions are
7 // met:
8 //
9 // * Redistributions of source code must retain the above copyright
10 // notice, this list of conditions and the following disclaimer.
11 // * Redistributions in binary form must reproduce the above
12 // copyright notice, this list of conditions and the following disclaimer
13 // in the documentation and/or other materials provided with the
14 // distribution.
15 // * Neither the name of Google Inc. nor the names of its
16 // contributors may be used to endorse or promote products derived from
17 // this software without specific prior written permission.
18 //
19 // THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
20 // "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
21 // LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
22 // A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
23 // OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
24 // SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
25 // LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
26 // DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
27 // THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
28 // (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
29 // OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
30 
31 // Authors: wink@google.com (Wink Saville),
32 // kenton@google.com (Kenton Varda)
33 // Based on original Protocol Buffers design by
34 // Sanjay Ghemawat, Jeff Dean, and others.
35 //
36 // Defines MessageLite, the abstract interface implemented by all (lite
37 // and non-lite) protocol message objects.
38 
39 #ifndef GOOGLE_PROTOBUF_MESSAGE_LITE_H__
40 #define GOOGLE_PROTOBUF_MESSAGE_LITE_H__
41 
42 #include <climits>
43 #include <google/protobuf/stubs/common.h>
44 #include <google/protobuf/stubs/logging.h>
45 #include <google/protobuf/stubs/once.h>
46 #include <google/protobuf/arena.h>
47 #include <google/protobuf/stubs/port.h>
48 
49 namespace google {
50 namespace protobuf {
51 template <typename T>
53 namespace io {
54 class CodedInputStream;
55 class CodedOutputStream;
56 class ZeroCopyInputStream;
57 class ZeroCopyOutputStream;
58 }
59 namespace internal {
60 
61 class RepeatedPtrFieldBase;
62 class WireFormatLite;
63 class WeakFieldMap;
64 
65 #ifndef SWIG
66 // We compute sizes as size_t but cache them as int. This function converts a
67 // computed size to a cached size. Since we don't proceed with serialization
68 // if the total size was > INT_MAX, it is not important what this function
69 // returns for inputs > INT_MAX. However this case should not error or
70 // GOOGLE_CHECK-fail, because the full size_t resolution is still returned from
71 // ByteSizeLong() and checked against INT_MAX; we can catch the overflow
72 // there.
73 inline int ToCachedSize(size_t size) { return static_cast<int>(size); }
74 
75 // We mainly calculate sizes in terms of size_t, but some functions that
76 // compute sizes return "int". These int sizes are expected to always be
77 // positive. This function is more efficient than casting an int to size_t
78 // directly on 64-bit platforms because it avoids making the compiler emit a
79 // sign extending instruction, which we don't want and don't want to pay for.
80 inline size_t FromIntSize(int size) {
81  // Convert to unsigned before widening so sign extension is not necessary.
82  return static_cast<unsigned int>(size);
83 }
84 
85 // For cases where a legacy function returns an integer size. We GOOGLE_DCHECK()
86 // that the conversion will fit within an integer; if this is false then we
87 // are losing information.
88 inline int ToIntSize(size_t size) {
89  GOOGLE_DCHECK_LE(size, static_cast<size_t>(INT_MAX));
90  return static_cast<int>(size);
91 }
92 
93 // This type wraps a variable whose constructor and destructor are explicitly
94 // called. It is particularly useful for a global variable, without its
95 // constructor and destructor run on start and end of the program lifetime.
96 // This circumvents the initial construction order fiasco, while keeping
97 // the address of the empty string a compile time constant.
98 //
99 // Pay special attention to the initialization state of the object.
100 // 1. The object is "uninitialized" to begin with.
101 // 2. Call DefaultConstruct() only if the object is uninitialized.
102 // After the call, the object becomes "initialized".
103 // 3. Call get() and get_mutable() only if the object is initialized.
104 // 4. Call Destruct() only if the object is initialized.
105 // After the call, the object becomes uninitialized.
106 template <typename T>
108  public:
110  new (&union_) T();
111  }
112 
113  void Destruct() {
114  get_mutable()->~T();
115  }
116 
117  constexpr const T& get() const { return reinterpret_cast<const T&>(union_); }
118  T* get_mutable() { return reinterpret_cast<T*>(&union_); }
119 
120  private:
121  // Prefer c++14 aligned_storage, but for compatibility this will do.
122  union AlignedUnion {
123  char space[sizeof(T)];
124  int64 align_to_int64;
125  void* align_to_ptr;
126  } union_;
127 };
128 
129 // Default empty string object. Don't use this directly. Instead, call
130 // GetEmptyString() to get the reference.
131 LIBPROTOBUF_EXPORT extern ExplicitlyConstructed<::std::string> fixed_address_empty_string;
132 
133 LIBPROTOBUF_EXPORT inline const ::std::string& GetEmptyStringAlreadyInited() {
134  return fixed_address_empty_string.get();
135 }
136 
137 LIBPROTOBUF_EXPORT size_t StringSpaceUsedExcludingSelfLong(const string& str);
138 #endif // SWIG
139 } // namespace internal
140 
141 // Interface to light weight protocol messages.
142 //
143 // This interface is implemented by all protocol message objects. Non-lite
144 // messages additionally implement the Message interface, which is a
145 // subclass of MessageLite. Use MessageLite instead when you only need
146 // the subset of features which it supports -- namely, nothing that uses
147 // descriptors or reflection. You can instruct the protocol compiler
148 // to generate classes which implement only MessageLite, not the full
149 // Message interface, by adding the following line to the .proto file:
150 //
151 // option optimize_for = LITE_RUNTIME;
152 //
153 // This is particularly useful on resource-constrained systems where
154 // the full protocol buffers runtime library is too big.
155 //
156 // Note that on non-constrained systems (e.g. servers) when you need
157 // to link in lots of protocol definitions, a better way to reduce
158 // total code footprint is to use optimize_for = CODE_SIZE. This
159 // will make the generated code smaller while still supporting all the
160 // same features (at the expense of speed). optimize_for = LITE_RUNTIME
161 // is best when you only have a small number of message types linked
162 // into your binary, in which case the size of the protocol buffers
163 // runtime itself is the biggest problem.
164 class LIBPROTOBUF_EXPORT MessageLite {
165  public:
166  inline MessageLite() {}
167  virtual ~MessageLite() {}
168 
169  // Basic Operations ------------------------------------------------
170 
171  // Get the name of this message type, e.g. "foo.bar.BazProto".
172  virtual string GetTypeName() const = 0;
173 
174  // Construct a new instance of the same type. Ownership is passed to the
175  // caller.
176  virtual MessageLite* New() const = 0;
177 
178  // Construct a new instance on the arena. Ownership is passed to the caller
179  // if arena is a NULL. Default implementation for backwards compatibility.
180  virtual MessageLite* New(::google::protobuf::Arena* arena) const;
181 
182  // Get the arena, if any, associated with this message. Virtual method
183  // required for generic operations but most arena-related operations should
184  // use the GetArenaNoVirtual() generated-code method. Default implementation
185  // to reduce code size by avoiding the need for per-type implementations
186  // when types do not implement arena support.
187  virtual ::google::protobuf::Arena* GetArena() const { return NULL; }
188 
189  // Get a pointer that may be equal to this message's arena, or may not be.
190  // If the value returned by this method is equal to some arena pointer, then
191  // this message is on that arena; however, if this message is on some arena,
192  // this method may or may not return that arena's pointer. As a tradeoff,
193  // this method may be more efficient than GetArena(). The intent is to allow
194  // underlying representations that use e.g. tagged pointers to sometimes
195  // store the arena pointer directly, and sometimes in a more indirect way,
196  // and allow a fastpath comparison against the arena pointer when it's easy
197  // to obtain.
198  virtual void* GetMaybeArenaPointer() const { return GetArena(); }
199 
200  // Clear all fields of the message and set them to their default values.
201  // Clear() avoids freeing memory, assuming that any memory allocated
202  // to hold parts of the message will be needed again to hold the next
203  // message. If you actually want to free the memory used by a Message,
204  // you must delete it.
205  virtual void Clear() = 0;
206 
207  // Quickly check if all required fields have values set.
208  virtual bool IsInitialized() const = 0;
209 
210  // This is not implemented for Lite messages -- it just returns "(cannot
211  // determine missing fields for lite message)". However, it is implemented
212  // for full messages. See message.h.
213  virtual string InitializationErrorString() const;
214 
215  // If |other| is the exact same class as this, calls MergeFrom(). Otherwise,
216  // results are undefined (probably crash).
217  virtual void CheckTypeAndMergeFrom(const MessageLite& other) = 0;
218 
219  // Parsing ---------------------------------------------------------
220  // Methods for parsing in protocol buffer format. Most of these are
221  // just simple wrappers around MergeFromCodedStream(). Clear() will be
222  // called before merging the input.
223 
224  // Fill the message with a protocol buffer parsed from the given input
225  // stream. Returns false on a read error or if the input is in the wrong
226  // format. A successful return does not indicate the entire input is
227  // consumed, ensure you call ConsumedEntireMessage() to check that if
228  // applicable.
229  bool ParseFromCodedStream(io::CodedInputStream* input);
230  // Like ParseFromCodedStream(), but accepts messages that are missing
231  // required fields.
232  bool ParsePartialFromCodedStream(io::CodedInputStream* input);
233  // Read a protocol buffer from the given zero-copy input stream. If
234  // successful, the entire input will be consumed.
235  bool ParseFromZeroCopyStream(io::ZeroCopyInputStream* input);
236  // Like ParseFromZeroCopyStream(), but accepts messages that are missing
237  // required fields.
238  bool ParsePartialFromZeroCopyStream(io::ZeroCopyInputStream* input);
239  // Read a protocol buffer from the given zero-copy input stream, expecting
240  // the message to be exactly "size" bytes long. If successful, exactly
241  // this many bytes will have been consumed from the input.
242  bool ParseFromBoundedZeroCopyStream(io::ZeroCopyInputStream* input, int size);
243  // Like ParseFromBoundedZeroCopyStream(), but accepts messages that are
244  // missing required fields.
245  bool ParsePartialFromBoundedZeroCopyStream(io::ZeroCopyInputStream* input,
246  int size);
247  // Parses a protocol buffer contained in a string. Returns true on success.
248  // This function takes a string in the (non-human-readable) binary wire
249  // format, matching the encoding output by MessageLite::SerializeToString().
250  // If you'd like to convert a human-readable string into a protocol buffer
251  // object, see google::protobuf::TextFormat::ParseFromString().
252  bool ParseFromString(const string& data);
253  // Like ParseFromString(), but accepts messages that are missing
254  // required fields.
255  bool ParsePartialFromString(const string& data);
256  // Parse a protocol buffer contained in an array of bytes.
257  bool ParseFromArray(const void* data, int size);
258  // Like ParseFromArray(), but accepts messages that are missing
259  // required fields.
260  bool ParsePartialFromArray(const void* data, int size);
261 
262 
263  // Reads a protocol buffer from the stream and merges it into this
264  // Message. Singular fields read from the what is
265  // already in the Message and repeated fields are appended to those
266  // already present.
267  //
268  // It is the responsibility of the caller to call input->LastTagWas()
269  // (for groups) or input->ConsumedEntireMessage() (for non-groups) after
270  // this returns to verify that the message's end was delimited correctly.
271  //
272  // ParsefromCodedStream() is implemented as Clear() followed by
273  // MergeFromCodedStream().
274  bool MergeFromCodedStream(io::CodedInputStream* input);
275 
276  // Like MergeFromCodedStream(), but succeeds even if required fields are
277  // missing in the input.
278  //
279  // MergeFromCodedStream() is just implemented as MergePartialFromCodedStream()
280  // followed by IsInitialized().
281  virtual bool MergePartialFromCodedStream(io::CodedInputStream* input) = 0;
282 
283 
284  // Serialization ---------------------------------------------------
285  // Methods for serializing in protocol buffer format. Most of these
286  // are just simple wrappers around ByteSize() and SerializeWithCachedSizes().
287 
288  // Write a protocol buffer of this message to the given output. Returns
289  // false on a write error. If the message is missing required fields,
290  // this may GOOGLE_CHECK-fail.
291  bool SerializeToCodedStream(io::CodedOutputStream* output) const;
292  // Like SerializeToCodedStream(), but allows missing required fields.
293  bool SerializePartialToCodedStream(io::CodedOutputStream* output) const;
294  // Write the message to the given zero-copy output stream. All required
295  // fields must be set.
296  bool SerializeToZeroCopyStream(io::ZeroCopyOutputStream* output) const;
297  // Like SerializeToZeroCopyStream(), but allows missing required fields.
298  bool SerializePartialToZeroCopyStream(io::ZeroCopyOutputStream* output) const;
299  // Serialize the message and store it in the given string. All required
300  // fields must be set.
301  bool SerializeToString(string* output) const;
302  // Like SerializeToString(), but allows missing required fields.
303  bool SerializePartialToString(string* output) const;
304  // Serialize the message and store it in the given byte array. All required
305  // fields must be set.
306  bool SerializeToArray(void* data, int size) const;
307  // Like SerializeToArray(), but allows missing required fields.
308  bool SerializePartialToArray(void* data, int size) const;
309 
310  // Make a string encoding the message. Is equivalent to calling
311  // SerializeToString() on a string and using that. Returns the empty
312  // string if SerializeToString() would have returned an error.
313  // Note: If you intend to generate many such strings, you may
314  // reduce heap fragmentation by instead re-using the same string
315  // object with calls to SerializeToString().
316  string SerializeAsString() const;
317  // Like SerializeAsString(), but allows missing required fields.
318  string SerializePartialAsString() const;
319 
320  // Like SerializeToString(), but appends to the data to the string's existing
321  // contents. All required fields must be set.
322  bool AppendToString(string* output) const;
323  // Like AppendToString(), but allows missing required fields.
324  bool AppendPartialToString(string* output) const;
325 
326  // Computes the serialized size of the message. This recursively calls
327  // ByteSizeLong() on all embedded messages.
328  //
329  // ByteSizeLong() is generally linear in the number of fields defined for the
330  // proto.
331  virtual size_t ByteSizeLong() const = 0;
332 
333  // Legacy ByteSize() API.
334  PROTOBUF_RUNTIME_DEPRECATED("Please use ByteSizeLong() instead")
335  int ByteSize() const {
337  }
338 
339  // Serializes the message without recomputing the size. The message must not
340  // have changed since the last call to ByteSize(), and the value returned by
341  // ByteSize must be non-negative. Otherwise the results are undefined.
342  virtual void SerializeWithCachedSizes(
343  io::CodedOutputStream* output) const;
344 
345  // Functions below here are not part of the public interface. It isn't
346  // enforced, but they should be treated as private, and will be private
347  // at some future time. Unfortunately the implementation of the "friend"
348  // keyword in GCC is broken at the moment, but we expect it will be fixed.
349 
350  // Like SerializeWithCachedSizes, but writes directly to *target, returning
351  // a pointer to the byte immediately after the last byte written. "target"
352  // must point at a byte array of at least ByteSize() bytes. Whether to use
353  // deterministic serialization, e.g., maps in sorted order, is determined by
354  // CodedOutputStream::IsDefaultSerializationDeterministic().
355  virtual uint8* SerializeWithCachedSizesToArray(uint8* target) const;
356 
357  // Returns the result of the last call to ByteSize(). An embedded message's
358  // size is needed both to serialize it (because embedded messages are
359  // length-delimited) and to compute the outer message's size. Caching
360  // the size avoids computing it multiple times.
361  //
362  // ByteSize() does not automatically use the cached size when available
363  // because this would require invalidating it every time the message was
364  // modified, which would be too hard and expensive. (E.g. if a deeply-nested
365  // sub-message is changed, all of its parents' cached sizes would need to be
366  // invalidated, which is too much work for an otherwise inlined setter
367  // method.)
368  virtual int GetCachedSize() const = 0;
369 
370  virtual uint8* InternalSerializeWithCachedSizesToArray(bool deterministic,
371  uint8* target) const;
372 
373  protected:
374  // CastToBase allows generated code to cast a RepeatedPtrField<T> to
375  // RepeatedPtrFieldBase. We try to restrict access to RepeatedPtrFieldBase
376  // because it is an implementation detail that user code should not access
377  // directly.
378  template <typename T>
379  static ::google::protobuf::internal::RepeatedPtrFieldBase* CastToBase(
381  return repeated;
382  }
383  template <typename T>
384  static const ::google::protobuf::internal::RepeatedPtrFieldBase& CastToBase(
385  const ::google::protobuf::RepeatedPtrField<T>& repeated) {
386  return repeated;
387  }
388 
389  template <typename T>
390  static T* CreateMaybeMessage(Arena* arena) {
391  return Arena::CreateMaybeMessage<T>(arena);
392  }
393 
394  private:
395  // TODO(gerbens) make this a pure abstract function
396  virtual const void* InternalGetTable() const { return NULL; }
397 
398  friend class internal::WireFormatLite;
399  friend class Message;
400  friend class internal::WeakFieldMap;
401 
402  GOOGLE_DISALLOW_EVIL_CONSTRUCTORS(MessageLite);
403 };
404 
405 namespace internal {
406 
407 extern bool LIBPROTOBUF_EXPORT proto3_preserve_unknown_;
408 
409 // DO NOT USE: For migration only. Will be removed when Proto3 defaults to
410 // preserve unknowns.
413 }
414 
415 // DO NOT USE: For migration only. Will be removed when Proto3 defaults to
416 // preserve unknowns.
417 void LIBPROTOBUF_EXPORT SetProto3PreserveUnknownsDefault(bool preserve);
418 } // namespace internal
419 
420 
421 } // namespace protobuf
422 
423 } // namespace google
424 #endif // GOOGLE_PROTOBUF_MESSAGE_LITE_H__
google::protobuf::RepeatedPtrField
Definition: message_lite.h:52
google::protobuf::internal::GetEmptyStringAlreadyInited
LIBPROTOBUF_EXPORTconst ::std::string & GetEmptyStringAlreadyInited()
Definition: message_lite.h:133
google::protobuf::internal::fixed_address_empty_string
LIBPROTOBUF_EXPORT ExplicitlyConstructed<::std::string > fixed_address_empty_string
google::protobuf::internal::proto3_preserve_unknown_
bool LIBPROTOBUF_EXPORT proto3_preserve_unknown_
google::protobuf::internal::FromIntSize
size_t FromIntSize(int size)
Definition: message_lite.h:80
google::protobuf::internal::GetProto3PreserveUnknownsDefault
bool GetProto3PreserveUnknownsDefault()
Definition: message_lite.h:411
google::protobuf::MessageLite
Definition: message_lite.h:164
google::protobuf::internal::SetProto3PreserveUnknownsDefault
void LIBPROTOBUF_EXPORT SetProto3PreserveUnknownsDefault(bool preserve)
goby::time::str
std::string str(TimeType value=SystemClock::now< TimeType >())
Returns the provided time (or current time if omitted) as a human-readable string.
Definition: convert.h:191
google::protobuf::Arena
Definition: arena.h:244
google::protobuf::MessageLite::CreateMaybeMessage
static T * CreateMaybeMessage(Arena *arena)
Definition: message_lite.h:390
google::protobuf::internal::ExplicitlyConstructed::Destruct
void Destruct()
Definition: message_lite.h:113
google::protobuf::internal::ToIntSize
int ToIntSize(size_t size)
Definition: message_lite.h:88
google::protobuf::MessageLite::GetMaybeArenaPointer
virtual void * GetMaybeArenaPointer() const
Definition: message_lite.h:198
google::protobuf::internal::StringSpaceUsedExcludingSelfLong
LIBPROTOBUF_EXPORT size_t StringSpaceUsedExcludingSelfLong(const string &str)
google::protobuf::internal::ExplicitlyConstructed::get
constexpr const T & get() const
Definition: message_lite.h:117
goby::int64
std::int64_t int64
Definition: primitive_types.h:35
google::protobuf::Message
Definition: message.h:189
google::protobuf::internal::ToCachedSize
int ToCachedSize(size_t size)
Definition: message_lite.h:73
ByteSizeLong
#define ByteSizeLong
Definition: protobuf_log_plugin.h:37
google::protobuf::internal::ExplicitlyConstructed::DefaultConstruct
void DefaultConstruct()
Definition: message_lite.h:109
arena.h
google::protobuf::internal::ExplicitlyConstructed::get_mutable
T * get_mutable()
Definition: message_lite.h:118
google::protobuf::MessageLite::MessageLite
MessageLite()
Definition: message_lite.h:166
google::protobuf::MessageLite::CastToBase
::google::protobuf::internal::RepeatedPtrFieldBase * CastToBase(::google::protobuf::RepeatedPtrField< T > *repeated)
Definition: message_lite.h:379
google::protobuf::internal::ExplicitlyConstructed
Definition: message_lite.h:107
google::protobuf::MessageLite::GetArena
virtual ::google::protobuf::Arena * GetArena() const
Definition: message_lite.h:187
google::protobuf::MessageLite::~MessageLite
virtual ~MessageLite()
Definition: message_lite.h:167
google
Definition: dccl.h:57
int
google::protobuf::MessageLite::CastToBase
static const ::google::protobuf::internal::RepeatedPtrFieldBase & CastToBase(const ::google::protobuf::RepeatedPtrField< T > &repeated)
Definition: message_lite.h:384