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 <string> |
35 | #include <type_traits> |
36 | #include <utility> |
37 | |
38 | #include <google/protobuf/stubs/logging.h> |
39 | #include <google/protobuf/stubs/common.h> |
40 | #include <google/protobuf/arena.h> |
41 | #include <google/protobuf/port.h> |
42 | |
43 | #include <google/protobuf/port_def.inc> |
44 | |
45 | #ifdef SWIG |
46 | #error "You cannot SWIG proto headers" |
47 | #endif |
48 | |
49 | |
50 | namespace google { |
51 | namespace protobuf { |
52 | namespace internal { |
53 | |
54 | template <typename T> |
55 | class ExplicitlyConstructed; |
56 | |
57 | class SwapFieldHelper; |
58 | |
59 | // Lazy string instance to support string fields with non-empty default. |
60 | // These are initialized on the first call to .get(). |
61 | class PROTOBUF_EXPORT LazyString { |
62 | public: |
63 | // We explicitly make LazyString an aggregate so that MSVC can do constant |
64 | // initialization on it without marking it `constexpr`. |
65 | // We do not want to use `constexpr` because it makes it harder to have extern |
66 | // storage for it and causes library bloat. |
67 | struct InitValue { |
68 | const char* ptr; |
69 | size_t size; |
70 | }; |
71 | // We keep a union of the initialization value and the std::string to save on |
72 | // space. We don't need the string array after Init() is done. |
73 | union { |
74 | mutable InitValue init_value_; |
75 | alignas(std::string) mutable char string_buf_[sizeof(std::string)]; |
76 | }; |
77 | mutable std::atomic<const std::string*> inited_; |
78 | |
79 | const std::string& get() const { |
80 | // This check generates less code than a call-once invocation. |
81 | auto* res = inited_.load(m: std::memory_order_acquire); |
82 | if (PROTOBUF_PREDICT_FALSE(res == nullptr)) return Init(); |
83 | return *res; |
84 | } |
85 | |
86 | private: |
87 | // Initialize the string in `string_buf_`, update `inited_` and return it. |
88 | // We return it here to avoid having to read it again in the inlined code. |
89 | const std::string& Init() const; |
90 | }; |
91 | |
92 | template <typename T> |
93 | class TaggedPtr { |
94 | public: |
95 | TaggedPtr() = default; |
96 | explicit constexpr TaggedPtr(const ExplicitlyConstructed<std::string>* ptr) |
97 | : ptr_(const_cast<ExplicitlyConstructed<std::string>*>(ptr)) {} |
98 | |
99 | void SetTagged(T* p) { |
100 | Set(p); |
101 | ptr_ = reinterpret_cast<void*>(as_int() | 1); |
102 | } |
103 | void Set(T* p) { ptr_ = p; } |
104 | T* Get() const { return reinterpret_cast<T*>(as_int() & -2); } |
105 | bool IsTagged() const { return as_int() & 1; } |
106 | |
107 | // Returned value is only safe to dereference if IsTagged() == false. |
108 | // It is safe to compare. |
109 | T* UnsafeGet() const { return static_cast<T*>(ptr_); } |
110 | |
111 | bool IsNull() { return ptr_ == nullptr; } |
112 | |
113 | private: |
114 | uintptr_t as_int() const { return reinterpret_cast<uintptr_t>(ptr_); } |
115 | void* ptr_; |
116 | }; |
117 | |
118 | static_assert(std::is_trivial<TaggedPtr<std::string>>::value, |
119 | "TaggedPtr must be trivial"); |
120 | |
121 | // This class encapsulates a pointer to a std::string with or without a donated |
122 | // buffer, tagged by bottom bit. It is a high-level wrapper that almost directly |
123 | // corresponds to the interface required by string fields in generated |
124 | // code. It replaces the old std::string* pointer in such cases. |
125 | // |
126 | // The object has different but similar code paths for when the default value is |
127 | // the empty string and when it is a non-empty string. |
128 | // The empty string is handled different throughout the library and there is a |
129 | // single global instance of it we can share. |
130 | // |
131 | // For fields with an empty string default value, there are three distinct |
132 | // states: |
133 | // |
134 | // - Pointer set to 'String' tag (LSB is 0), equal to |
135 | // &GetEmptyStringAlreadyInited(): field is set to its default value. Points |
136 | // to a true std::string*, but we do not own that std::string* (it's a |
137 | // globally shared instance). |
138 | // |
139 | // - Pointer set to 'String' tag (LSB is 0), but not equal to the global empty |
140 | // string: field points to a true std::string* instance that we own. This |
141 | // instance is either on the heap or on the arena (i.e. registered on |
142 | // free()/destructor-call list) as appropriate. |
143 | // |
144 | // - Pointer set to 'DonatedString' tag (LSB is 1): points to a std::string |
145 | // instance with a buffer on the arena (arena is never nullptr in this case). |
146 | // |
147 | // For fields with a non-empty string default value, there are three distinct |
148 | // states: |
149 | // |
150 | // - Pointer set to 'String' tag (LSB is 0), equal to `nullptr`: |
151 | // Field is in "default" mode and does not point to any actual instance. |
152 | // Methods that might need to create an instance of the object will pass a |
153 | // `const LazyString&` for it. |
154 | // |
155 | // - Pointer set to 'String' tag (LSB is 0), but not equal to `nullptr`: |
156 | // field points to a true std::string* instance that we own. This instance is |
157 | // either on the heap or on the arena (i.e. registered on |
158 | // free()/destructor-call list) as appropriate. |
159 | // |
160 | // - Pointer set to 'DonatedString' tag (LSB is 1): points to a std::string |
161 | // instance with a buffer on the arena (arena is never nullptr in this case). |
162 | // |
163 | // Generated code and reflection code both ensure that ptr_ is never null for |
164 | // fields with an empty default. |
165 | // Because ArenaStringPtr is used in oneof unions, its constructor is a NOP and |
166 | // so the field is always manually initialized via method calls. |
167 | // |
168 | // Side-note: why pass information about the default on every API call? Because |
169 | // we don't want to hold it in a member variable, or else this would go into |
170 | // every proto message instance. This would be a huge waste of space, since the |
171 | // default instance pointer is typically a global (static class field). We want |
172 | // the generated code to be as efficient as possible, and if we take |
173 | // the default value information as a parameter that's in practice taken from a |
174 | // static class field, and compare ptr_ to the default value, we end up with a |
175 | // single "cmp %reg, GLOBAL" in the resulting machine code. (Note that this also |
176 | // requires the String tag to be 0 so we can avoid the mask before comparing.) |
177 | struct PROTOBUF_EXPORT ArenaStringPtr { |
178 | ArenaStringPtr() = default; |
179 | explicit constexpr ArenaStringPtr( |
180 | const ExplicitlyConstructed<std::string>* default_value) |
181 | : tagged_ptr_(default_value) {} |
182 | |
183 | // Some methods below are overloaded on a `default_value` and on tags. |
184 | // The tagged overloads help reduce code size in the callers in generated |
185 | // code, while the `default_value` overloads are useful from reflection. |
186 | // By-value empty struct arguments are elided in the ABI. |
187 | struct EmptyDefault {}; |
188 | struct NonEmptyDefault {}; |
189 | |
190 | void Set(const std::string* default_value, ConstStringParam value, |
191 | ::google::protobuf::Arena* arena); |
192 | void Set(const std::string* default_value, std::string&& value, |
193 | ::google::protobuf::Arena* arena); |
194 | void Set(EmptyDefault, ConstStringParam value, ::google::protobuf::Arena* arena); |
195 | void Set(EmptyDefault, std::string&& value, ::google::protobuf::Arena* arena); |
196 | void Set(NonEmptyDefault, ConstStringParam value, ::google::protobuf::Arena* arena); |
197 | void Set(NonEmptyDefault, std::string&& value, ::google::protobuf::Arena* arena); |
198 | template <typename FirstParam> |
199 | void Set(FirstParam p1, const char* str, ::google::protobuf::Arena* arena) { |
200 | Set(p1, ConstStringParam(str), arena); |
201 | } |
202 | template <typename FirstParam> |
203 | void Set(FirstParam p1, const char* str, size_t size, |
204 | ::google::protobuf::Arena* arena) { |
205 | ConstStringParam sp{str, size}; // for string_view and `const string &` |
206 | Set(p1, sp, arena); |
207 | } |
208 | template <typename FirstParam, typename RefWrappedType> |
209 | void Set(FirstParam p1, |
210 | std::reference_wrapper<RefWrappedType> const_string_ref, |
211 | ::google::protobuf::Arena* arena) { |
212 | Set(p1, const_string_ref.get(), arena); |
213 | } |
214 | |
215 | template <typename FirstParam, typename SecondParam> |
216 | void SetBytes(FirstParam p1, SecondParam&& p2, ::google::protobuf::Arena* arena) { |
217 | Set(p1, static_cast<SecondParam&&>(p2), arena); |
218 | } |
219 | template <typename FirstParam> |
220 | void SetBytes(FirstParam p1, const void* str, size_t size, |
221 | ::google::protobuf::Arena* arena) { |
222 | // must work whether ConstStringParam is string_view or `const string &` |
223 | ConstStringParam sp{static_cast<const char*>(str), size}; |
224 | Set(p1, sp, arena); |
225 | } |
226 | |
227 | // Basic accessors. |
228 | PROTOBUF_NDEBUG_INLINE const std::string& Get() const { |
229 | // Unconditionally mask away the tag. |
230 | return *tagged_ptr_.Get(); |
231 | } |
232 | PROTOBUF_NDEBUG_INLINE const std::string* GetPointer() const { |
233 | // Unconditionally mask away the tag. |
234 | return tagged_ptr_.Get(); |
235 | } |
236 | |
237 | // For fields with an empty default value. |
238 | std::string* Mutable(EmptyDefault, ::google::protobuf::Arena* arena); |
239 | // For fields with a non-empty default value. |
240 | std::string* Mutable(const LazyString& default_value, ::google::protobuf::Arena* arena); |
241 | |
242 | // Release returns a std::string* instance that is heap-allocated and is not |
243 | // Own()'d by any arena. If the field is not set, this returns nullptr. The |
244 | // caller retains ownership. Clears this field back to nullptr state. Used to |
245 | // implement release_<field>() methods on generated classes. |
246 | PROTOBUF_NODISCARD std::string* Release(const std::string* default_value, |
247 | ::google::protobuf::Arena* arena); |
248 | PROTOBUF_NODISCARD std::string* ReleaseNonDefault( |
249 | const std::string* default_value, ::google::protobuf::Arena* arena); |
250 | |
251 | // Takes a std::string that is heap-allocated, and takes ownership. The |
252 | // std::string's destructor is registered with the arena. Used to implement |
253 | // set_allocated_<field> in generated classes. |
254 | void SetAllocated(const std::string* default_value, std::string* value, |
255 | ::google::protobuf::Arena* arena); |
256 | |
257 | // Swaps internal pointers. Arena-safety semantics: this is guarded by the |
258 | // logic in Swap()/UnsafeArenaSwap() at the message level, so this method is |
259 | // 'unsafe' if called directly. |
260 | inline PROTOBUF_NDEBUG_INLINE static void InternalSwap( |
261 | const std::string* default_value, ArenaStringPtr* rhs, Arena* rhs_arena, |
262 | ArenaStringPtr* lhs, Arena* lhs_arena); |
263 | |
264 | // Frees storage (if not on an arena). |
265 | void Destroy(const std::string* default_value, ::google::protobuf::Arena* arena); |
266 | void Destroy(EmptyDefault, ::google::protobuf::Arena* arena); |
267 | void Destroy(NonEmptyDefault, ::google::protobuf::Arena* arena); |
268 | |
269 | // Clears content, but keeps allocated std::string, to avoid the overhead of |
270 | // heap operations. After this returns, the content (as seen by the user) will |
271 | // always be the empty std::string. Assumes that |default_value| is an empty |
272 | // std::string. |
273 | void ClearToEmpty(); |
274 | |
275 | // Clears content, assuming that the current value is not the empty |
276 | // string default. |
277 | void ClearNonDefaultToEmpty(); |
278 | |
279 | // Clears content, but keeps allocated std::string if arena != nullptr, to |
280 | // avoid the overhead of heap operations. After this returns, the content |
281 | // (as seen by the user) will always be equal to |default_value|. |
282 | void ClearToDefault(const LazyString& default_value, ::google::protobuf::Arena* arena); |
283 | |
284 | // Called from generated code / reflection runtime only. Resets value to point |
285 | // to a default string pointer, with the semantics that this |
286 | // ArenaStringPtr does not own the pointed-to memory. Disregards initial value |
287 | // of ptr_ (so this is the *ONLY* safe method to call after construction or |
288 | // when reinitializing after becoming the active field in a oneof union). |
289 | inline void UnsafeSetDefault(const std::string* default_value); |
290 | |
291 | // Returns a mutable pointer, but doesn't initialize the string to the |
292 | // default value. |
293 | std::string* MutableNoArenaNoDefault(const std::string* default_value); |
294 | |
295 | // Get a mutable pointer with unspecified contents. |
296 | // Similar to `MutableNoArenaNoDefault`, but also handles the arena case. |
297 | // If the value was donated, the contents are discarded. |
298 | std::string* MutableNoCopy(const std::string* default_value, |
299 | ::google::protobuf::Arena* arena); |
300 | |
301 | // Destroy the string. Assumes `arena == nullptr`. |
302 | void DestroyNoArena(const std::string* default_value); |
303 | |
304 | // Internal setter used only at parse time to directly set a donated string |
305 | // value. |
306 | void UnsafeSetTaggedPointer(TaggedPtr<std::string> value) { |
307 | tagged_ptr_ = value; |
308 | } |
309 | // Generated code only! An optimization, in certain cases the generated |
310 | // code is certain we can obtain a std::string with no default checks and |
311 | // tag tests. |
312 | std::string* UnsafeMutablePointer() PROTOBUF_RETURNS_NONNULL; |
313 | |
314 | inline bool IsDefault(const std::string* default_value) const { |
315 | // Relies on the fact that kPtrTagString == 0, so if IsString(), ptr_ is the |
316 | // actual std::string pointer (and if !IsString(), ptr_ will never be equal |
317 | // to any aligned |default_value| pointer). The key is that we want to avoid |
318 | // masking in the fastpath const-pointer Get() case for non-arena code. |
319 | return tagged_ptr_.UnsafeGet() == default_value; |
320 | } |
321 | |
322 | private: |
323 | TaggedPtr<std::string> tagged_ptr_; |
324 | |
325 | bool IsDonatedString() const { return false; } |
326 | |
327 | // Swaps tagged pointer without debug hardening. This is to allow python |
328 | // protobuf to maintain pointer stability even in DEBUG builds. |
329 | inline PROTOBUF_NDEBUG_INLINE static void UnsafeShallowSwap( |
330 | ArenaStringPtr* rhs, ArenaStringPtr* lhs) { |
331 | std::swap(a&: lhs->tagged_ptr_, b&: rhs->tagged_ptr_); |
332 | } |
333 | |
334 | friend class ::google::protobuf::internal::SwapFieldHelper; |
335 | |
336 | // Slow paths. |
337 | |
338 | // MutableSlow requires that !IsString() || IsDefault |
339 | // Variadic to support 0 args for EmptyDefault and 1 arg for LazyString. |
340 | template <typename... Lazy> |
341 | std::string* MutableSlow(::google::protobuf::Arena* arena, const Lazy&... lazy_default); |
342 | |
343 | // Sets value to a newly allocated string and returns it |
344 | std::string* SetAndReturnNewString(); |
345 | |
346 | // Destroys the non-default string value out-of-line |
347 | void DestroyNoArenaSlowPath(); |
348 | |
349 | }; |
350 | |
351 | inline void ArenaStringPtr::UnsafeSetDefault(const std::string* value) { |
352 | tagged_ptr_.Set(const_cast<std::string*>(value)); |
353 | } |
354 | |
355 | // Make sure rhs_arena allocated rhs, and lhs_arena allocated lhs. |
356 | inline PROTOBUF_NDEBUG_INLINE void ArenaStringPtr::InternalSwap( // |
357 | const std::string* default_value, // |
358 | ArenaStringPtr* rhs, Arena* rhs_arena, // |
359 | ArenaStringPtr* lhs, Arena* lhs_arena) { |
360 | // Silence unused variable warnings in release buildls. |
361 | (void)default_value; |
362 | (void)rhs_arena; |
363 | (void)lhs_arena; |
364 | std::swap(a&: lhs->tagged_ptr_, b&: rhs->tagged_ptr_); |
365 | #ifdef PROTOBUF_FORCE_COPY_IN_SWAP |
366 | auto force_realloc = [default_value](ArenaStringPtr* p, Arena* arena) { |
367 | if (p->IsDefault(default_value)) return; |
368 | std::string* old_value = p->tagged_ptr_.Get(); |
369 | std::string* new_value = |
370 | p->IsDonatedString() |
371 | ? Arena::Create<std::string>(arena, *old_value) |
372 | : Arena::Create<std::string>(arena, std::move(*old_value)); |
373 | if (arena == nullptr) delete old_value; |
374 | p->tagged_ptr_.Set(new_value); |
375 | }; |
376 | // Because, at this point, tagged_ptr_ has been swapped, arena should also be |
377 | // swapped. |
378 | force_realloc(lhs, rhs_arena); |
379 | force_realloc(rhs, lhs_arena); |
380 | #endif // PROTOBUF_FORCE_COPY_IN_SWAP |
381 | } |
382 | |
383 | inline void ArenaStringPtr::ClearNonDefaultToEmpty() { |
384 | // Unconditionally mask away the tag. |
385 | tagged_ptr_.Get()->clear(); |
386 | } |
387 | |
388 | inline std::string* ArenaStringPtr::MutableNoArenaNoDefault( |
389 | const std::string* default_value) { |
390 | // VERY IMPORTANT for performance and code size: this will reduce to a member |
391 | // variable load, a pointer check (against |default_value|, in practice a |
392 | // static global) and a branch to the slowpath (which calls operator new and |
393 | // the ctor). DO NOT add any tagged-pointer operations here. |
394 | if (IsDefault(default_value)) { |
395 | return SetAndReturnNewString(); |
396 | } else { |
397 | return UnsafeMutablePointer(); |
398 | } |
399 | } |
400 | |
401 | inline void ArenaStringPtr::DestroyNoArena(const std::string* default_value) { |
402 | if (!IsDefault(default_value)) { |
403 | DestroyNoArenaSlowPath(); |
404 | } |
405 | } |
406 | |
407 | inline std::string* ArenaStringPtr::UnsafeMutablePointer() { |
408 | GOOGLE_DCHECK(!tagged_ptr_.IsTagged()); |
409 | GOOGLE_DCHECK(tagged_ptr_.UnsafeGet() != nullptr); |
410 | return tagged_ptr_.UnsafeGet(); |
411 | } |
412 | |
413 | |
414 | } // namespace internal |
415 | } // namespace protobuf |
416 | } // namespace google |
417 | |
418 | #include <google/protobuf/port_undef.inc> |
419 | |
420 | #endif // GOOGLE_PROTOBUF_ARENASTRING_H__ |
421 |
Definitions
- LazyString
- InitValue
- get
- TaggedPtr
- TaggedPtr
- TaggedPtr
- SetTagged
- Set
- Get
- IsTagged
- UnsafeGet
- IsNull
- as_int
- ArenaStringPtr
- ArenaStringPtr
- ArenaStringPtr
- EmptyDefault
- NonEmptyDefault
- Set
- Set
- Set
- SetBytes
- SetBytes
- Get
- GetPointer
- UnsafeSetTaggedPointer
- IsDefault
- IsDonatedString
- UnsafeShallowSwap
- UnsafeSetDefault
- InternalSwap
- ClearNonDefaultToEmpty
- MutableNoArenaNoDefault
- DestroyNoArena
Update your C++ knowledge – Modern C++11/14/17 Training
Find out more