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#ifndef GOOGLE_PROTOBUF_ARENASTRING_H__
32#define GOOGLE_PROTOBUF_ARENASTRING_H__
33
34#include <algorithm>
35#include <string>
36#include <type_traits>
37#include <utility>
38
39#include <google/protobuf/stubs/logging.h>
40#include <google/protobuf/stubs/common.h>
41#include <google/protobuf/arena.h>
42#include <google/protobuf/port.h>
43#include <google/protobuf/explicitly_constructed.h>
44
45// must be last:
46#include <google/protobuf/port_def.inc>
47
48#ifdef SWIG
49#error "You cannot SWIG proto headers"
50#endif
51
52
53namespace google {
54namespace protobuf {
55namespace internal {
56class EpsCopyInputStream;
57
58class SwapFieldHelper;
59
60// Declared in message_lite.h
61PROTOBUF_EXPORT extern ExplicitlyConstructedArenaString
62 fixed_address_empty_string;
63
64// Lazy string instance to support string fields with non-empty default.
65// These are initialized on the first call to .get().
66class PROTOBUF_EXPORT LazyString {
67 public:
68 // We explicitly make LazyString an aggregate so that MSVC can do constant
69 // initialization on it without marking it `constexpr`.
70 // We do not want to use `constexpr` because it makes it harder to have extern
71 // storage for it and causes library bloat.
72 struct InitValue {
73 const char* ptr;
74 size_t size;
75 };
76 // We keep a union of the initialization value and the std::string to save on
77 // space. We don't need the string array after Init() is done.
78 union {
79 mutable InitValue init_value_;
80 alignas(std::string) mutable char string_buf_[sizeof(std::string)];
81 };
82 mutable std::atomic<const std::string*> inited_;
83
84 const std::string& get() const {
85 // This check generates less code than a call-once invocation.
86 auto* res = inited_.load(m: std::memory_order_acquire);
87 if (PROTOBUF_PREDICT_FALSE(res == nullptr)) return Init();
88 return *res;
89 }
90
91 private:
92 // Initialize the string in `string_buf_`, update `inited_` and return it.
93 // We return it here to avoid having to read it again in the inlined code.
94 const std::string& Init() const;
95};
96
97class TaggedStringPtr {
98 public:
99 // Bit flags qualifying string properties. We can use 2 bits as
100 // ptr_ is guaranteed and enforced to be aligned on 4 byte boundaries.
101 enum Flags {
102 kArenaBit = 0x1, // ptr is arena allocated
103 kMutableBit = 0x2, // ptr contents are fully mutable
104 kMask = 0x3 // Bit mask
105 };
106
107 // Composed logical types
108 enum Type {
109 // Default strings are immutable and never owned.
110 kDefault = 0,
111
112 // Allocated strings are mutable and (as the name implies) owned.
113 // A heap allocated string must be deleted.
114 kAllocated = kMutableBit,
115
116 // Mutable arena strings are strings where the string instance is owned
117 // by the arena, but the string contents itself are owned by the string
118 // instance. Mutable arena string instances need to be destroyed which is
119 // typically done through a cleanup action added to the arena owning it.
120 kMutableArena = kArenaBit | kMutableBit,
121
122 // Fixed size arena strings are strings where both the string instance and
123 // the string contents are fully owned by the arena. Fixed size arena
124 // strings are a platform and c++ library specific customization. Fixed
125 // size arena strings are immutable, with the exception of custom internal
126 // updates to the content that fit inside the existing capacity.
127 // Fixed size arena strings must never be deleted or destroyed.
128 kFixedSizeArena = kArenaBit,
129 };
130
131 TaggedStringPtr() = default;
132 explicit constexpr TaggedStringPtr(ExplicitlyConstructedArenaString* ptr)
133 : ptr_(ptr) {}
134
135 // Sets the value to `p`, tagging the value as being a 'default' value.
136 // See documentation for kDefault for more info.
137 inline const std::string* SetDefault(const std::string* p) {
138 return TagAs(type: kDefault, p: const_cast<std::string*>(p));
139 }
140
141 // Sets the value to `p`, tagging the value as a heap allocated value.
142 // Allocated strings are mutable and (as the name implies) owned.
143 // `p` must not be null
144 inline std::string* SetAllocated(std::string* p) {
145 return TagAs(type: kAllocated, p);
146 }
147
148 // Sets the value to `p`, tagging the value as a fixed size arena string.
149 // See documentation for kFixedSizeArena for more info.
150 // `p` must not be null
151 inline std::string* SetFixedSizeArena(std::string* p) {
152 return TagAs(type: kFixedSizeArena, p);
153 }
154
155 // Sets the value to `p`, tagging the value as a mutable arena string.
156 // See documentation for kMutableArena for more info.
157 // `p` must not be null
158 inline std::string* SetMutableArena(std::string* p) {
159 return TagAs(type: kMutableArena, p);
160 }
161
162 // Returns true if the contents of the current string are fully mutable.
163 inline bool IsMutable() const { return as_int() & kMutableBit; }
164
165 // Returns true if the current string is an immutable default value.
166 inline bool IsDefault() const { return (as_int() & kMask) == kDefault; }
167
168 // If the current string is a heap-allocated mutable value, returns a pointer
169 // to it. Returns nullptr otherwise.
170 inline std::string *GetIfAllocated() const {
171 auto allocated = as_int() ^ kAllocated;
172 if (allocated & kMask) return nullptr;
173
174 auto ptr = reinterpret_cast<std::string*>(allocated);
175 PROTOBUF_ASSUME(ptr != nullptr);
176 return ptr;
177 }
178
179 // Returns true if the current string is an arena allocated value.
180 // This means it's either a mutable or fixed size arena string.
181 inline bool IsArena() const { return as_int() & kArenaBit; }
182
183 // Returns true if the current string is a fixed size arena allocated value.
184 inline bool IsFixedSizeArena() const {
185 return (as_int() & kMask) == kFixedSizeArena;
186 }
187
188 // Returns the contained string pointer.
189 inline std::string* Get() const {
190 return reinterpret_cast<std::string*>(as_int() & ~kMask);
191 }
192
193 // Returns true if the contained pointer is null, indicating some error.
194 // The Null value is only used during parsing for temporary values.
195 // A persisted ArenaStringPtr value is never null.
196 inline bool IsNull() { return ptr_ == nullptr; }
197
198 private:
199 static inline void assert_aligned(const void* p) {
200 GOOGLE_DCHECK_EQ(reinterpret_cast<uintptr_t>(p) & kMask, 0UL);
201 }
202
203 inline std::string* TagAs(Type type, std::string* p) {
204 GOOGLE_DCHECK(p != nullptr);
205 assert_aligned(p);
206 ptr_ = reinterpret_cast<void*>(reinterpret_cast<uintptr_t>(p) | type);
207 return p;
208 }
209
210 uintptr_t as_int() const { return reinterpret_cast<uintptr_t>(ptr_); }
211 void* ptr_;
212};
213
214static_assert(std::is_trivial<TaggedStringPtr>::value,
215 "TaggedStringPtr must be trivial");
216
217// This class encapsulates a pointer to a std::string with or without arena
218// owned contents, tagged by the bottom bits of the string pointer. It is a
219// high-level wrapper that almost directly corresponds to the interface required
220// by string fields in generated code. It replaces the old std::string* pointer
221// in such cases.
222//
223// The string pointer is tagged to be either a default, externally owned value,
224// a mutable heap allocated value, or an arena allocated value. The object uses
225// a single global instance of an empty string that is used as the initial
226// default value. Fields that have empty default values directly use this global
227// default. Fields that have non empty default values are supported through
228// lazily initialized default values managed by the LazyString class.
229//
230// Generated code and reflection code both ensure that ptr_ is never null.
231// Because ArenaStringPtr is used in oneof unions, its constructor is a NOP and
232// the field is always manually initialized via method calls.
233//
234// See TaggedStringPtr for more information about the types of string values
235// being held, and the mutable and ownership invariants for each type.
236struct PROTOBUF_EXPORT ArenaStringPtr {
237 ArenaStringPtr() = default;
238 constexpr ArenaStringPtr(ExplicitlyConstructedArenaString* default_value,
239 ConstantInitialized)
240 : tagged_ptr_(default_value) {}
241
242 // Called from generated code / reflection runtime only. Resets value to point
243 // to a default string pointer, with the semantics that this ArenaStringPtr
244 // does not own the pointed-to memory. Disregards initial value of ptr_ (so
245 // this is the *ONLY* safe method to call after construction or when
246 // reinitializing after becoming the active field in a oneof union).
247 inline void InitDefault();
248
249 // Similar to `InitDefault` except that it allows the default value to be
250 // initialized to an externally owned string. This method is called from
251 // parsing code. `str` must not be null and outlive this instance.
252 inline void InitExternal(const std::string* str);
253
254 // Called from generated code / reflection runtime only. Resets the value of
255 // this instances to the heap allocated value in `str`. `str` must not be
256 // null. Invokes `arena->Own(str)` to transfer ownership into the arena if
257 // `arena` is not null, else, `str` will be owned by ArenaStringPtr. This
258 // function should only be used to initialize a ArenaStringPtr or on an
259 // instance known to not carry any heap allocated value.
260 inline void InitAllocated(std::string* str, Arena* arena);
261
262 void Set(ConstStringParam value, Arena* arena);
263 void Set(std::string&& value, Arena* arena);
264 void Set(const char* s, Arena* arena);
265 void Set(const char* s, size_t n, Arena* arena);
266
267 void SetBytes(ConstStringParam value, Arena* arena);
268 void SetBytes(std::string&& value, Arena* arena);
269 void SetBytes(const char* s, Arena* arena);
270 void SetBytes(const void* p, size_t n, Arena* arena);
271
272 template <typename RefWrappedType>
273 void Set(std::reference_wrapper<RefWrappedType> const_string_ref,
274 ::google::protobuf::Arena* arena) {
275 Set(const_string_ref.get(), arena);
276 }
277
278 // Returns a mutable std::string reference.
279 // The version accepting a `LazyString` value is used in the generated code to
280 // initialize mutable copies for fields with a non-empty default where the
281 // default value is lazily initialized.
282 std::string* Mutable(Arena* arena);
283 std::string* Mutable(const LazyString& default_value, Arena* arena);
284
285 // Gets a mutable pointer with unspecified contents.
286 // This function is identical to Mutable(), except it is optimized for the
287 // case where the caller is not interested in the current contents. For
288 // example, if the current field is not mutable, it will re-initialize the
289 // value with an empty string rather than a (non-empty) default value.
290 // Likewise, if the current value is a fixed size arena string with contents,
291 // it will be initialized into an empty mutable arena string.
292 std::string* MutableNoCopy(Arena* arena);
293
294 // Basic accessors.
295 PROTOBUF_NDEBUG_INLINE const std::string& Get() const {
296 // Unconditionally mask away the tag.
297 return *tagged_ptr_.Get();
298 }
299
300 // Returns a pointer to the stored contents for this instance.
301 // This method is for internal debugging and tracking purposes only.
302 PROTOBUF_NDEBUG_INLINE const std::string* UnsafeGetPointer() const
303 PROTOBUF_RETURNS_NONNULL {
304 return tagged_ptr_.Get();
305 }
306
307 // Release returns a std::string* instance that is heap-allocated and is not
308 // Own()'d by any arena. If the field is not set, this returns nullptr. The
309 // caller retains ownership. Clears this field back to the default state.
310 // Used to implement release_<field>() methods on generated classes.
311 PROTOBUF_NODISCARD std::string* Release();
312
313 // Takes a std::string that is heap-allocated, and takes ownership. The
314 // std::string's destructor is registered with the arena. Used to implement
315 // set_allocated_<field> in generated classes.
316 void SetAllocated(std::string* value, Arena* arena);
317
318 // Frees storage (if not on an arena).
319 void Destroy();
320
321 // Clears content, but keeps allocated std::string, to avoid the overhead of
322 // heap operations. After this returns, the content (as seen by the user) will
323 // always be the empty std::string. Assumes that |default_value| is an empty
324 // std::string.
325 void ClearToEmpty();
326
327 // Clears content, assuming that the current value is not the empty
328 // string default.
329 void ClearNonDefaultToEmpty();
330
331 // Clears content, but keeps allocated std::string if arena != nullptr, to
332 // avoid the overhead of heap operations. After this returns, the content
333 // (as seen by the user) will always be equal to |default_value|.
334 void ClearToDefault(const LazyString& default_value, ::google::protobuf::Arena* arena);
335
336 // Swaps internal pointers. Arena-safety semantics: this is guarded by the
337 // logic in Swap()/UnsafeArenaSwap() at the message level, so this method is
338 // 'unsafe' if called directly.
339 inline PROTOBUF_NDEBUG_INLINE static void InternalSwap(ArenaStringPtr* rhs,
340 Arena* rhs_arena,
341 ArenaStringPtr* lhs,
342 Arena* lhs_arena);
343
344 // Internal setter used only at parse time to directly set a donated string
345 // value.
346 void UnsafeSetTaggedPointer(TaggedStringPtr value) { tagged_ptr_ = value; }
347 // Generated code only! An optimization, in certain cases the generated
348 // code is certain we can obtain a std::string with no default checks and
349 // tag tests.
350 std::string* UnsafeMutablePointer() PROTOBUF_RETURNS_NONNULL;
351
352 // Returns true if this instances holds an immutable default value.
353 inline bool IsDefault() const { return tagged_ptr_.IsDefault(); }
354
355 private:
356 template <typename... Args>
357 inline std::string* NewString(Arena* arena, Args&&... args) {
358 if (arena == nullptr) {
359 auto* s = new std::string(std::forward<Args>(args)...);
360 return tagged_ptr_.SetAllocated(s);
361 } else {
362 auto* s = Arena::Create<std::string>(arena, std::forward<Args>(args)...);
363 return tagged_ptr_.SetMutableArena(s);
364 }
365 }
366
367 TaggedStringPtr tagged_ptr_;
368
369 bool IsFixedSizeArena() const { return false; }
370
371 // Swaps tagged pointer without debug hardening. This is to allow python
372 // protobuf to maintain pointer stability even in DEBUG builds.
373 inline PROTOBUF_NDEBUG_INLINE static void UnsafeShallowSwap(
374 ArenaStringPtr* rhs, ArenaStringPtr* lhs) {
375 std::swap(a&: lhs->tagged_ptr_, b&: rhs->tagged_ptr_);
376 }
377
378 friend class ::google::protobuf::internal::SwapFieldHelper;
379 friend class TcParser;
380
381 // Slow paths.
382
383 // MutableSlow requires that !IsString() || IsDefault
384 // Variadic to support 0 args for empty default and 1 arg for LazyString.
385 template <typename... Lazy>
386 std::string* MutableSlow(::google::protobuf::Arena* arena, const Lazy&... lazy_default);
387
388 friend class EpsCopyInputStream;
389};
390
391inline void ArenaStringPtr::InitDefault() {
392 tagged_ptr_ = TaggedStringPtr(&fixed_address_empty_string);
393}
394
395inline void ArenaStringPtr::InitExternal(const std::string* str) {
396 tagged_ptr_.SetDefault(str);
397}
398
399inline void ArenaStringPtr::InitAllocated(std::string* str, Arena* arena) {
400 if (arena != nullptr) {
401 tagged_ptr_.SetMutableArena(str);
402 arena->Own(object: str);
403 } else {
404 tagged_ptr_.SetAllocated(str);
405 }
406}
407
408inline void ArenaStringPtr::Set(const char* s, Arena* arena) {
409 Set(value: ConstStringParam{s}, arena);
410}
411
412inline void ArenaStringPtr::Set(const char* s, size_t n, Arena* arena) {
413 Set(value: ConstStringParam{s, n}, arena);
414}
415
416inline void ArenaStringPtr::SetBytes(ConstStringParam value, Arena* arena) {
417 Set(value, arena);
418}
419
420inline void ArenaStringPtr::SetBytes(std::string&& value, Arena* arena) {
421 Set(value: std::move(value), arena);
422}
423
424inline void ArenaStringPtr::SetBytes(const char* s, Arena* arena) {
425 Set(s, arena);
426}
427
428inline void ArenaStringPtr::SetBytes(const void* p, size_t n, Arena* arena) {
429 Set(value: ConstStringParam{static_cast<const char*>(p), n}, arena);
430}
431
432// Make sure rhs_arena allocated rhs, and lhs_arena allocated lhs.
433inline PROTOBUF_NDEBUG_INLINE void ArenaStringPtr::InternalSwap( //
434 ArenaStringPtr* rhs, Arena* rhs_arena, //
435 ArenaStringPtr* lhs, Arena* lhs_arena) {
436 // Silence unused variable warnings in release buildls.
437 (void)rhs_arena;
438 (void)lhs_arena;
439 std::swap(a&: lhs->tagged_ptr_, b&: rhs->tagged_ptr_);
440#ifdef PROTOBUF_FORCE_COPY_IN_SWAP
441 auto force_realloc = [](ArenaStringPtr* p, Arena* arena) {
442 if (p->IsDefault()) return;
443 std::string* old_value = p->tagged_ptr_.Get();
444 std::string* new_value =
445 p->IsFixedSizeArena()
446 ? Arena::Create<std::string>(arena, *old_value)
447 : Arena::Create<std::string>(arena, std::move(*old_value));
448 if (arena == nullptr) {
449 delete old_value;
450 p->tagged_ptr_.SetAllocated(new_value);
451 } else {
452 p->tagged_ptr_.SetMutableArena(new_value);
453 }
454 };
455 // Because, at this point, tagged_ptr_ has been swapped, arena should also be
456 // swapped.
457 force_realloc(lhs, rhs_arena);
458 force_realloc(rhs, lhs_arena);
459#endif // PROTOBUF_FORCE_COPY_IN_SWAP
460}
461
462inline void ArenaStringPtr::ClearNonDefaultToEmpty() {
463 // Unconditionally mask away the tag.
464 tagged_ptr_.Get()->clear();
465}
466
467inline std::string* ArenaStringPtr::UnsafeMutablePointer() {
468 GOOGLE_DCHECK(tagged_ptr_.IsMutable());
469 GOOGLE_DCHECK(tagged_ptr_.Get() != nullptr);
470 return tagged_ptr_.Get();
471}
472
473
474} // namespace internal
475} // namespace protobuf
476} // namespace google
477
478#include <google/protobuf/port_undef.inc>
479
480#endif // GOOGLE_PROTOBUF_ARENASTRING_H__
481