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: [email protected] (Wink Saville),
32// [email protected] (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 <string>
44
45#include <google/protobuf/stubs/common.h>
46#include <google/protobuf/stubs/logging.h>
47#include <google/protobuf/io/coded_stream.h>
48#include <google/protobuf/arena.h>
49#include <google/protobuf/stubs/once.h>
50#include <google/protobuf/port.h>
51#include <google/protobuf/stubs/strutil.h>
52
53
54#include <google/protobuf/port_def.inc>
55
56#ifdef SWIG
57#error "You cannot SWIG proto headers"
58#endif
59
60namespace google {
61namespace protobuf {
62
63template <typename T>
64class RepeatedPtrField;
65
66namespace io {
67
68class CodedInputStream;
69class CodedOutputStream;
70class ZeroCopyInputStream;
71class ZeroCopyOutputStream;
72
73} // namespace io
74namespace internal {
75
76// See parse_context.h for explanation
77class ParseContext;
78
79class RepeatedPtrFieldBase;
80class WireFormatLite;
81class WeakFieldMap;
82
83// We compute sizes as size_t but cache them as int. This function converts a
84// computed size to a cached size. Since we don't proceed with serialization
85// if the total size was > INT_MAX, it is not important what this function
86// returns for inputs > INT_MAX. However this case should not error or
87// GOOGLE_CHECK-fail, because the full size_t resolution is still returned from
88// ByteSizeLong() and checked against INT_MAX; we can catch the overflow
89// there.
90inline int ToCachedSize(size_t size) { return static_cast<int>(size); }
91
92// We mainly calculate sizes in terms of size_t, but some functions that
93// compute sizes return "int". These int sizes are expected to always be
94// positive. This function is more efficient than casting an int to size_t
95// directly on 64-bit platforms because it avoids making the compiler emit a
96// sign extending instruction, which we don't want and don't want to pay for.
97inline size_t FromIntSize(int size) {
98 // Convert to unsigned before widening so sign extension is not necessary.
99 return static_cast<unsigned int>(size);
100}
101
102// For cases where a legacy function returns an integer size. We GOOGLE_DCHECK()
103// that the conversion will fit within an integer; if this is false then we
104// are losing information.
105inline int ToIntSize(size_t size) {
106 GOOGLE_DCHECK_LE(size, static_cast<size_t>(INT_MAX));
107 return static_cast<int>(size);
108}
109
110// This type wraps a variable whose constructor and destructor are explicitly
111// called. It is particularly useful for a global variable, without its
112// constructor and destructor run on start and end of the program lifetime.
113// This circumvents the initial construction order fiasco, while keeping
114// the address of the empty string a compile time constant.
115//
116// Pay special attention to the initialization state of the object.
117// 1. The object is "uninitialized" to begin with.
118// 2. Call Construct() or DefaultConstruct() only if the object is
119// uninitialized. After the call, the object becomes "initialized".
120// 3. Call get() and get_mutable() only if the object is initialized.
121// 4. Call Destruct() only if the object is initialized.
122// After the call, the object becomes uninitialized.
123template <typename T>
124class ExplicitlyConstructed {
125 public:
126 void DefaultConstruct() { new (&union_) T(); }
127
128 template <typename... Args>
129 void Construct(Args&&... args) {
130 new (&union_) T(std::forward<Args>(args)...);
131 }
132
133 void Destruct() { get_mutable()->~T(); }
134
135 constexpr const T& get() const { return reinterpret_cast<const T&>(union_); }
136 T* get_mutable() { return reinterpret_cast<T*>(&union_); }
137
138 private:
139 // Prefer c++14 aligned_storage, but for compatibility this will do.
140 union AlignedUnion {
141 char space[sizeof(T)];
142 int64 align_to_int64;
143 void* align_to_ptr;
144 } union_;
145};
146
147// Default empty string object. Don't use this directly. Instead, call
148// GetEmptyString() to get the reference.
149PROTOBUF_EXPORT extern ExplicitlyConstructed<std::string>
150 fixed_address_empty_string;
151
152
153PROTOBUF_EXPORT inline const std::string& GetEmptyStringAlreadyInited() {
154 return fixed_address_empty_string.get();
155}
156
157PROTOBUF_EXPORT size_t StringSpaceUsedExcludingSelfLong(const std::string& str);
158
159} // namespace internal
160
161// Interface to light weight protocol messages.
162//
163// This interface is implemented by all protocol message objects. Non-lite
164// messages additionally implement the Message interface, which is a
165// subclass of MessageLite. Use MessageLite instead when you only need
166// the subset of features which it supports -- namely, nothing that uses
167// descriptors or reflection. You can instruct the protocol compiler
168// to generate classes which implement only MessageLite, not the full
169// Message interface, by adding the following line to the .proto file:
170//
171// option optimize_for = LITE_RUNTIME;
172//
173// This is particularly useful on resource-constrained systems where
174// the full protocol buffers runtime library is too big.
175//
176// Note that on non-constrained systems (e.g. servers) when you need
177// to link in lots of protocol definitions, a better way to reduce
178// total code footprint is to use optimize_for = CODE_SIZE. This
179// will make the generated code smaller while still supporting all the
180// same features (at the expense of speed). optimize_for = LITE_RUNTIME
181// is best when you only have a small number of message types linked
182// into your binary, in which case the size of the protocol buffers
183// runtime itself is the biggest problem.
184class PROTOBUF_EXPORT MessageLite {
185 public:
186 inline MessageLite() {}
187 virtual ~MessageLite() {}
188
189 // Basic Operations ------------------------------------------------
190
191 // Get the name of this message type, e.g. "foo.bar.BazProto".
192 virtual std::string GetTypeName() const = 0;
193
194 // Construct a new instance of the same type. Ownership is passed to the
195 // caller.
196 virtual MessageLite* New() const = 0;
197
198 // Construct a new instance on the arena. Ownership is passed to the caller
199 // if arena is a NULL. Default implementation for backwards compatibility.
200 virtual MessageLite* New(Arena* arena) const;
201
202 // Get the arena, if any, associated with this message. Virtual method
203 // required for generic operations but most arena-related operations should
204 // use the GetArenaNoVirtual() generated-code method. Default implementation
205 // to reduce code size by avoiding the need for per-type implementations
206 // when types do not implement arena support.
207 virtual Arena* GetArena() const { return NULL; }
208
209 // Get a pointer that may be equal to this message's arena, or may not be.
210 // If the value returned by this method is equal to some arena pointer, then
211 // this message is on that arena; however, if this message is on some arena,
212 // this method may or may not return that arena's pointer. As a tradeoff,
213 // this method may be more efficient than GetArena(). The intent is to allow
214 // underlying representations that use e.g. tagged pointers to sometimes
215 // store the arena pointer directly, and sometimes in a more indirect way,
216 // and allow a fastpath comparison against the arena pointer when it's easy
217 // to obtain.
218 virtual void* GetMaybeArenaPointer() const { return GetArena(); }
219
220 // Clear all fields of the message and set them to their default values.
221 // Clear() avoids freeing memory, assuming that any memory allocated
222 // to hold parts of the message will be needed again to hold the next
223 // message. If you actually want to free the memory used by a Message,
224 // you must delete it.
225 virtual void Clear() = 0;
226
227 // Quickly check if all required fields have values set.
228 virtual bool IsInitialized() const = 0;
229
230 // This is not implemented for Lite messages -- it just returns "(cannot
231 // determine missing fields for lite message)". However, it is implemented
232 // for full messages. See message.h.
233 virtual std::string InitializationErrorString() const;
234
235 // If |other| is the exact same class as this, calls MergeFrom(). Otherwise,
236 // results are undefined (probably crash).
237 virtual void CheckTypeAndMergeFrom(const MessageLite& other) = 0;
238
239 // These methods return a human-readable summary of the message. Note that
240 // since the MessageLite interface does not support reflection, there is very
241 // little information that these methods can provide. They are shadowed by
242 // methods of the same name on the Message interface which provide much more
243 // information. The methods here are intended primarily to facilitate code
244 // reuse for logic that needs to interoperate with both full and lite protos.
245 //
246 // The format of the returned string is subject to change, so please do not
247 // assume it will remain stable over time.
248 std::string DebugString() const;
249 std::string ShortDebugString() const { return DebugString(); }
250 // MessageLite::DebugString is already Utf8 Safe. This is to add compatibility
251 // with Message.
252 std::string Utf8DebugString() const { return DebugString(); }
253
254 // Parsing ---------------------------------------------------------
255 // Methods for parsing in protocol buffer format. Most of these are
256 // just simple wrappers around MergeFromCodedStream(). Clear() will be
257 // called before merging the input.
258
259 // Fill the message with a protocol buffer parsed from the given input
260 // stream. Returns false on a read error or if the input is in the wrong
261 // format. A successful return does not indicate the entire input is
262 // consumed, ensure you call ConsumedEntireMessage() to check that if
263 // applicable.
264 bool ParseFromCodedStream(io::CodedInputStream* input);
265 // Like ParseFromCodedStream(), but accepts messages that are missing
266 // required fields.
267 bool ParsePartialFromCodedStream(io::CodedInputStream* input);
268 // Read a protocol buffer from the given zero-copy input stream. If
269 // successful, the entire input will be consumed.
270 bool ParseFromZeroCopyStream(io::ZeroCopyInputStream* input);
271 // Like ParseFromZeroCopyStream(), but accepts messages that are missing
272 // required fields.
273 bool ParsePartialFromZeroCopyStream(io::ZeroCopyInputStream* input);
274 // Parse a protocol buffer from a file descriptor. If successful, the entire
275 // input will be consumed.
276 bool ParseFromFileDescriptor(int file_descriptor);
277 // Like ParseFromFileDescriptor(), but accepts messages that are missing
278 // required fields.
279 bool ParsePartialFromFileDescriptor(int file_descriptor);
280 // Parse a protocol buffer from a C++ istream. If successful, the entire
281 // input will be consumed.
282 bool ParseFromIstream(std::istream* input);
283 // Like ParseFromIstream(), but accepts messages that are missing
284 // required fields.
285 bool ParsePartialFromIstream(std::istream* input);
286 // Read a protocol buffer from the given zero-copy input stream, expecting
287 // the message to be exactly "size" bytes long. If successful, exactly
288 // this many bytes will have been consumed from the input.
289 bool MergePartialFromBoundedZeroCopyStream(io::ZeroCopyInputStream* input,
290 int size);
291 // Like ParseFromBoundedZeroCopyStream(), but accepts messages that are
292 // missing required fields.
293 bool MergeFromBoundedZeroCopyStream(io::ZeroCopyInputStream* input, int size);
294 bool ParseFromBoundedZeroCopyStream(io::ZeroCopyInputStream* input, int size);
295 // Like ParseFromBoundedZeroCopyStream(), but accepts messages that are
296 // missing required fields.
297 bool ParsePartialFromBoundedZeroCopyStream(io::ZeroCopyInputStream* input,
298 int size);
299 // Parses a protocol buffer contained in a string. Returns true on success.
300 // This function takes a string in the (non-human-readable) binary wire
301 // format, matching the encoding output by MessageLite::SerializeToString().
302 // If you'd like to convert a human-readable string into a protocol buffer
303 // object, see google::protobuf::TextFormat::ParseFromString().
304 bool ParseFromString(const std::string& data);
305 // Like ParseFromString(), but accepts messages that are missing
306 // required fields.
307 bool ParsePartialFromString(const std::string& data);
308 // Parse a protocol buffer contained in an array of bytes.
309 bool ParseFromArray(const void* data, int size);
310 // Like ParseFromArray(), but accepts messages that are missing
311 // required fields.
312 bool ParsePartialFromArray(const void* data, int size);
313
314
315 // Reads a protocol buffer from the stream and merges it into this
316 // Message. Singular fields read from the what is
317 // already in the Message and repeated fields are appended to those
318 // already present.
319 //
320 // It is the responsibility of the caller to call input->LastTagWas()
321 // (for groups) or input->ConsumedEntireMessage() (for non-groups) after
322 // this returns to verify that the message's end was delimited correctly.
323 //
324 // ParseFromCodedStream() is implemented as Clear() followed by
325 // MergeFromCodedStream().
326 bool MergeFromCodedStream(io::CodedInputStream* input);
327
328 // Like MergeFromCodedStream(), but succeeds even if required fields are
329 // missing in the input.
330 //
331 // MergeFromCodedStream() is just implemented as MergePartialFromCodedStream()
332 // followed by IsInitialized().
333 bool MergePartialFromCodedStream(io::CodedInputStream* input);
334
335 // Merge a protocol buffer contained in a string.
336 bool MergeFromString(const std::string& data);
337
338
339 // Serialization ---------------------------------------------------
340 // Methods for serializing in protocol buffer format. Most of these
341 // are just simple wrappers around ByteSize() and SerializeWithCachedSizes().
342
343 // Write a protocol buffer of this message to the given output. Returns
344 // false on a write error. If the message is missing required fields,
345 // this may GOOGLE_CHECK-fail.
346 bool SerializeToCodedStream(io::CodedOutputStream* output) const;
347 // Like SerializeToCodedStream(), but allows missing required fields.
348 bool SerializePartialToCodedStream(io::CodedOutputStream* output) const;
349 // Write the message to the given zero-copy output stream. All required
350 // fields must be set.
351 bool SerializeToZeroCopyStream(io::ZeroCopyOutputStream* output) const;
352 // Like SerializeToZeroCopyStream(), but allows missing required fields.
353 bool SerializePartialToZeroCopyStream(io::ZeroCopyOutputStream* output) const;
354 // Serialize the message and store it in the given string. All required
355 // fields must be set.
356 bool SerializeToString(std::string* output) const;
357 // Like SerializeToString(), but allows missing required fields.
358 bool SerializePartialToString(std::string* output) const;
359 // Serialize the message and store it in the given byte array. All required
360 // fields must be set.
361 bool SerializeToArray(void* data, int size) const;
362 // Like SerializeToArray(), but allows missing required fields.
363 bool SerializePartialToArray(void* data, int size) const;
364
365 // Make a string encoding the message. Is equivalent to calling
366 // SerializeToString() on a string and using that. Returns the empty
367 // string if SerializeToString() would have returned an error.
368 // Note: If you intend to generate many such strings, you may
369 // reduce heap fragmentation by instead re-using the same string
370 // object with calls to SerializeToString().
371 std::string SerializeAsString() const;
372 // Like SerializeAsString(), but allows missing required fields.
373 std::string SerializePartialAsString() const;
374
375 // Serialize the message and write it to the given file descriptor. All
376 // required fields must be set.
377 bool SerializeToFileDescriptor(int file_descriptor) const;
378 // Like SerializeToFileDescriptor(), but allows missing required fields.
379 bool SerializePartialToFileDescriptor(int file_descriptor) const;
380 // Serialize the message and write it to the given C++ ostream. All
381 // required fields must be set.
382 bool SerializeToOstream(std::ostream* output) const;
383 // Like SerializeToOstream(), but allows missing required fields.
384 bool SerializePartialToOstream(std::ostream* output) const;
385
386 // Like SerializeToString(), but appends to the data to the string's
387 // existing contents. All required fields must be set.
388 bool AppendToString(std::string* output) const;
389 // Like AppendToString(), but allows missing required fields.
390 bool AppendPartialToString(std::string* output) const;
391
392
393 // Computes the serialized size of the message. This recursively calls
394 // ByteSizeLong() on all embedded messages.
395 //
396 // ByteSizeLong() is generally linear in the number of fields defined for the
397 // proto.
398 virtual size_t ByteSizeLong() const = 0;
399
400 // Legacy ByteSize() API.
401 PROTOBUF_DEPRECATED_MSG("Please use ByteSizeLong() instead")
402 int ByteSize() const { return internal::ToIntSize(ByteSizeLong()); }
403
404 // Serializes the message without recomputing the size. The message must not
405 // have changed since the last call to ByteSize(), and the value returned by
406 // ByteSize must be non-negative. Otherwise the results are undefined.
407 void SerializeWithCachedSizes(io::CodedOutputStream* output) const {
408 output->SetCur(_InternalSerialize(output->Cur(), output->EpsCopy()));
409 }
410
411 // Functions below here are not part of the public interface. It isn't
412 // enforced, but they should be treated as private, and will be private
413 // at some future time. Unfortunately the implementation of the "friend"
414 // keyword in GCC is broken at the moment, but we expect it will be fixed.
415
416 // Like SerializeWithCachedSizes, but writes directly to *target, returning
417 // a pointer to the byte immediately after the last byte written. "target"
418 // must point at a byte array of at least ByteSize() bytes. Whether to use
419 // deterministic serialization, e.g., maps in sorted order, is determined by
420 // CodedOutputStream::IsDefaultSerializationDeterministic().
421 uint8* SerializeWithCachedSizesToArray(uint8* target) const;
422
423 // Returns the result of the last call to ByteSize(). An embedded message's
424 // size is needed both to serialize it (because embedded messages are
425 // length-delimited) and to compute the outer message's size. Caching
426 // the size avoids computing it multiple times.
427 //
428 // ByteSize() does not automatically use the cached size when available
429 // because this would require invalidating it every time the message was
430 // modified, which would be too hard and expensive. (E.g. if a deeply-nested
431 // sub-message is changed, all of its parents' cached sizes would need to be
432 // invalidated, which is too much work for an otherwise inlined setter
433 // method.)
434 virtual int GetCachedSize() const = 0;
435
436 virtual const char* _InternalParse(const char* /*ptr*/,
437 internal::ParseContext* /*ctx*/) {
438 return nullptr;
439 }
440
441 protected:
442 template <typename T>
443 static T* CreateMaybeMessage(Arena* arena) {
444 return Arena::CreateMaybeMessage<T>(arena);
445 }
446
447 public:
448 enum ParseFlags {
449 kMerge = 0,
450 kParse = 1,
451 kMergePartial = 2,
452 kParsePartial = 3,
453 kMergeWithAliasing = 4,
454 kParseWithAliasing = 5,
455 kMergePartialWithAliasing = 6,
456 kParsePartialWithAliasing = 7
457 };
458
459 template <ParseFlags flags, typename T>
460 bool ParseFrom(const T& input);
461
462 // Fast path when conditions match (ie. non-deterministic)
463 // uint8* _InternalSerialize(uint8* ptr) const;
464 virtual uint8* _InternalSerialize(uint8* ptr,
465 io::EpsCopyOutputStream* stream) const = 0;
466
467 private:
468 // TODO(gerbens) make this a pure abstract function
469 virtual const void* InternalGetTable() const { return NULL; }
470
471 friend class internal::WireFormatLite;
472 friend class Message;
473 friend class internal::WeakFieldMap;
474
475 bool IsInitializedWithErrors() const {
476 if (IsInitialized()) return true;
477 LogInitializationErrorMessage();
478 return false;
479 }
480
481 void LogInitializationErrorMessage() const;
482
483 GOOGLE_DISALLOW_EVIL_CONSTRUCTORS(MessageLite);
484};
485
486namespace internal {
487
488template <bool alias>
489bool MergePartialFromImpl(StringPiece input, MessageLite* msg);
490extern template bool MergePartialFromImpl<false>(StringPiece input,
491 MessageLite* msg);
492extern template bool MergePartialFromImpl<true>(StringPiece input,
493 MessageLite* msg);
494
495template <bool alias>
496bool MergePartialFromImpl(io::ZeroCopyInputStream* input, MessageLite* msg);
497extern template bool MergePartialFromImpl<false>(io::ZeroCopyInputStream* input,
498 MessageLite* msg);
499extern template bool MergePartialFromImpl<true>(io::ZeroCopyInputStream* input,
500 MessageLite* msg);
501
502struct BoundedZCIS {
503 io::ZeroCopyInputStream* zcis;
504 int limit;
505};
506
507template <bool alias>
508bool MergePartialFromImpl(BoundedZCIS input, MessageLite* msg);
509extern template bool MergePartialFromImpl<false>(BoundedZCIS input,
510 MessageLite* msg);
511extern template bool MergePartialFromImpl<true>(BoundedZCIS input,
512 MessageLite* msg);
513
514template <typename T>
515struct SourceWrapper;
516
517template <bool alias, typename T>
518bool MergePartialFromImpl(const SourceWrapper<T>& input, MessageLite* msg) {
519 return input.template MergePartialInto<alias>(msg);
520}
521
522} // namespace internal
523
524template <MessageLite::ParseFlags flags, typename T>
525bool MessageLite::ParseFrom(const T& input) {
526 if (flags & kParse) Clear();
527 constexpr bool alias = flags & kMergeWithAliasing;
528 bool res = internal::MergePartialFromImpl<alias>(input, this);
529 return res && ((flags & kMergePartial) || IsInitializedWithErrors());
530}
531
532// ===================================================================
533// Shutdown support.
534
535
536// Shut down the entire protocol buffers library, deleting all static-duration
537// objects allocated by the library or by generated .pb.cc files.
538//
539// There are two reasons you might want to call this:
540// * You use a draconian definition of "memory leak" in which you expect
541// every single malloc() to have a corresponding free(), even for objects
542// which live until program exit.
543// * You are writing a dynamically-loaded library which needs to clean up
544// after itself when the library is unloaded.
545//
546// It is safe to call this multiple times. However, it is not safe to use
547// any other part of the protocol buffers library after
548// ShutdownProtobufLibrary() has been called. Furthermore this call is not
549// thread safe, user needs to synchronize multiple calls.
550PROTOBUF_EXPORT void ShutdownProtobufLibrary();
551
552namespace internal {
553
554// Register a function to be called when ShutdownProtocolBuffers() is called.
555PROTOBUF_EXPORT void OnShutdown(void (*func)());
556// Run an arbitrary function on an arg
557PROTOBUF_EXPORT void OnShutdownRun(void (*f)(const void*), const void* arg);
558
559template <typename T>
560T* OnShutdownDelete(T* p) {
561 OnShutdownRun([](const void* pp) { delete static_cast<const T*>(pp); }, p);
562 return p;
563}
564
565} // namespace internal
566} // namespace protobuf
567} // namespace google
568
569#include <google/protobuf/port_undef.inc>
570
571#endif // GOOGLE_PROTOBUF_MESSAGE_LITE_H__
572